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1. INTRODUCTION 


About this book 

This book will teach you how to write programs using Locomotive Software’s 
BASIC 2 programming language (BASIC 2). It is divided into five main parts: 

• Part I: INTRODUCTION - an initial introduction to the facilities of BASIC 2 for all 
users 

• Part II: INTRODUCTION TO PROGRAMMING - tuition in programming with 
BASIC 2, suitable for users who have never written computer programs before 

• Part III: PROGRAMMING WITH BASIC 2 - a detailed description of the majority of 
the facilities of BASIC 2, suitable for users who are either already familiar with 
computer programming using other languages, or have worked through Part n 

• Part IV: ADVANCED FACILITIES - advanced and esoteric facilities, for more serious 
users 

• Part V: REFERENCE: appendices summarising BASIC 2 facilities 

Each Part starts with its own contents list, describing the chapters it contains. 
Subdivisions within chapters are called sections: their subdivisions are called 
subsections. 

While this guide contains all the information you should need to learn how to 
program with BASIC 2. you may occasionally need to refer to the other manuals 
provided with your computer system for further details such as operating the 
computer, preparing discs and using GEM menus. If you are entirely new to 
programming, you may also find helpful a book especially written to teach BASIC 
programming. 

Suggested reading approach 

Whatever your background, you are advised to start off by reading through this part, 
Part I, to gain an appreciation of the facilities available. The best course after that 
depends on your previous experience of computers and your temperament! 

If you are new to computers 

If you are new to computers you should carry on by reading Part II. performing the 
exercises using your computer. This will introduce you to the main concepts of 
programming and give you some practice in applying them. 

Don't try to work all the way through Part II without a break: you'll probably need 
time to digest some of the information. Ideally, read a chapter at a time. Do attempt 
all the exercises - they're designed to check your understanding and provide 
guidance where a crucial point has been missed. Feel free to experiment, for 
example by seeing what effect changing the examples has. 

If you get stuck and the HINTs can't help, you may find it helpful to read other 
books on programming with BASIC, although the version they describe will probably 
lack many of the extra facilities provided by BASIC 2. 
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Once you have finished Part n, you should be able to design, write and use 
programs to solve problems of moderate complexity, using the simple subset of 
BASIC 2 facilities introduced there. Check your understanding by attempting the 
concluding exercises and revise any chapters that you're not sure of. 

Once you are familiar with the basic concepts, you are ready to learn about the full 
range of BASIC 2 facilities, by reading Part III and Part IV. 

Part ID describes in greater detail all the facilities already introduced in Part II, along 
with many other facilities. This includes all the facilities that a typical user will want 
to use for most of the time. 

Part IV describes additional facilities that are mainly provided for writers of 'serious' 
programs. 

Parts HI and IV are structured rather differently to Part II, describing facilities in 
groups and going into considerable technical detail. The amount of technical detail 
may seem rather exhaustive (if not exhausting!), but it's all there to give you the 
complete story. The first time you read through these parts, feel free to skip over 
facilities that confuse or do not interest you; you can always return to them later, 
when you need or want to learn about them. Although at certain stages (such as 
program examples) you will be expected to have digested all previous information, 
you can always sneak a look back! 

A detailed index and contents lists are provided to make it easier to find particular 
items. 

If you have programmed before 

If you have programmed before, you will probably not need or want to read Part II in 
much detail, as it is mainly concerned with teaching the principles of programming. 
You should, however, look at its contents list, to check if there are any concepts 
described there that you are not familiar with. 

In Part III you will find all the facilities that a typical user will need to use, for most 
of the time. 

Part IV describes additional facilities that are mainly provided for writers of ‘serious 1 
programs, such as error handling and sophisticated disc filing. 

Pans III and IV describe facilities in groups (numeric functions, structuring, input, 
graphics, etc), going into considerable detail. They have a dual purpose: to 
introduce you to all the facilities provided by BASIC 2 and to provide you with 
reference information on all the facilities from now on. For this reason, they may 
seem rather exhaustive at first! Feel free to skip over facilities that confuse or do not 
interest you initially; you can always return to them later, when you need or want to 
learn about them. Although at certain stages (such as program examples) you will 
be expected to have digested all previous information, you can always sneak a look 
back! 

A detailed index and contents lists are provided to make it easier to find particular 
items. 







Conventions 


Throughout this book, special types of text will be used to represent different types 
of information, as follows: 

description 

- a description of the information, rather than the information itself. For example, 
number means 1 or 2 or 3 etc. If the description consists of more than one word, the 
words will be joined by hyphens, for example numeric-expression. 

(an option] 

- a part which can be omitted or included. (Usually producing a different result in 
each case.) 

[repeat...] 

- a part which may be omitted or included or even repeated 

something displayed on the screen 

- text displayed on the computer screen. 

Type: something to type 

- text for you to type, such as an instruction to the computer. 

GOTO. FINDS. OR etc 

- BASIC 2 keywords (special words that BASIC 2 recognises) are always shown in 
capitals. It does not matter whether you type these as capitals or small letters ; they 
will be converted to capitals automatically when stored in a program. 

count, pointer, a etc 

- when used in program examples, these are 'identifiers' invented by the user 
(variables, record names, procedure names, etc) as opposed to keywords. It does not 
matter whether you type identifiers using small or capital letters; they will be 
converted to small letters automatically when stored in a program. 


- used to pick out a part ot the text on the preceding line. Usually followed by an 
explanation of that text, on the next line. 

(see GOTO), (see FINDS), (see OR) etc 

- for further information, look up this word in the index. 

I Ctrl | . | Del | etC 

- the key on the computer keyboard marked | cm 1 . 1 o* | etc. not the letters 
CTRL. Your keyboard may use slightly different key names (such as CTRL rather 
than Ctrl), but the key intended should be clear. 

Ctrl-C 

- the key combination used to interrupt what the computer is doing, usually by 
holding down I cm I and pressing C. 

- press this key (the carriage-return key) 
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2. AN INTRODUCTION TO BASIC 2 


What BASIC 2 is for 

BASIC 2 is a programming language, for preparing and using programs to solve 
problems involving logic, calculation, text and graphics (pictures), and data 
handling. 

Its main ancestor is the original BASIC programming language, designed many years 
ago as a programming language that was simple to leam. to aid teaching. Since 
then, many versions of BASIC have been developed, mainly to run on modern 
microcomputers. BASIC 2 is a powerful BASIC enhanced with many structuring 
features and designed to run in a GEM environment to take advantage of many of 
its attractive features. 

BASIC 2 has many advantages over more ordinary BASICS, such as: 

- easy access to facilities, through GEM menus 

- attractive, easy-to-use GEM graphics and turtle graphics 

- flexible use of the display, through GEM windows 

- easy use of indexed (database-like) disk files 

You can use BASIC 2 very simply and easily as a kind of sophisticated calculator. Its 
main role, however, is as a programming language, for developing and using 
programs. 

BASIC 2 programs can be used for a wide range of different tasks, from simple 
things such as totalling sequences of figures, to complex jobs such as drawing 
pictures, calculating a payroll, performing statistical analysis or displaying and 
manipulating complex graphs. 

BASIC 2 allows you to use suitable programs written by others, as well as writing 
and using your own. It is a very versatile language which can be used to perform 
most tasks that involve manipulating numbers or text. 

This section provides a brief introduction to BASIC 2. After reading it, we suggest 
you go on the Guided Tour provided by Section 2.1 - to see for yourself what BASIC 
2 can do. 

Entering BASIC 2 

To use BASIC 2, you must first enter GEM. then open BASIC 2 as an application, 
from the GEM Desktop. 

The steps are as follows: 

1 Display the GEM Desktop, with one of the directory windows showing the root 
directory of Drive A (A:\). 

If you are not sure how to do this, consult your computer's user guide. 
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2 Place the BASIC 2 disk in Drive A and then press I e»c | 

3 Move the pointer to the BASIC2 folder and double-click the lefthand mouse button. 

The contents of the BASIC2 folder should now be displayed in this window (see 
below). If the folder is merely highlighted, you didn't double-click at the right speed. 
Try double-clicking the mouse button again - perhaps varying the speed at which 
you click - until you see the following display: 
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6ASIC2.APP 
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tun 

tun 

DEMO.BAS 



4 Move the pointer to the BASIC2 program icon and double-click the lefthand mouse 
button. Alternatively, if you want to run a particular BASIC program you have stored 
on disk, move the pointer to this program’s icon and double-click the lefthand 
mouse button. 

The pointer should be replaced by an hour glass and the BASIC 2 software read into 
the PC's memory. If the icon merely becomes highlighted, try double-clicking the 
mouse button again - perhaps varying the speed at which you click, or use the 
Open... option in the File menu. 

Once the software has been read into your PC's memory, the screen should show 
something like this: 


fill Pr«jr« Edit Fonts Colours Patterns lines Windows BASIC? 
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If BASIC 2 doesn’t load, it probably means that there isn’t enough memory available 
for the program to run. Reset your PC and try again. If BASIC 2 still fails to load, you 
may have to reduce the number of screen and printer fonts you have available. Your 
computer's user guide should explain how to do this. If in doubt, consult your 
dealer. 

Using BASIC 2 

The operation of items such as windows, menus and mouse in BASIC 2 is much the 
same as in other GEM applications, although* of course the functions they perform 
are all concerned with preparing and running BASIC 2 programs. The description of 
using these items is therefore very brief: tum to your GEM user guide for details if 
you are not familiar with using GEM applications. 

Keyboard and mouse 

BASIC 2 is controlled using two main devices: the mouse and keyboard. 

The mouse is used to select menu options, move and scroll windows, move the 
cursor, etc. 

The keyboard is used to type text and numbers, such as commands, file names, or 
the lines of a program you are writing and as an alternative to using the mouse. 

The general details of these devices will be given in your computer's user guide. 
However, the following keystrokes have particular importance when using BASIC 2: 

I <-> | - this is used to complete instructions, program lines and replies to requests 
for information when using programs and menu options 

Ctrl-C (ie. hold down the I cm I key and press [CD - this is used to interrupt 
whatever BASIC 2 is doing, for example to stop a program while it is running. 

Many menu options can be selected by pressing single keys, instead of using the 
mouse. Where this is the case, the key to use will be shown in the menu, at the 
extreme right of the option’s line. Often these will be shown as fn; this means 
function key n. However, these keystrokes can only be used when there isn't a 
menu on the screen. 

Be careful to distinguish between the keys used to type the number zero (0) and the 
letter 'Oh' (0). While they look similar, they are NOT interchangeable! 

Menus 

Menus provide you with lists of related commands or options, that can be picked 
using the mouse. They are used to help save you time and effort, by presenting you 
with a list of available options, rather than expecting you to remember lots of 
commands. 

To view the options in a menu, select it by moving the mouse pointer to its title in 
the menu bar. This causes the list of options in the menu to 'drop' onto the screen. 
Some of the options may not be available - these are shown fainter than those that 
are available. 

To remove a menu from the screen, move the mouse to anywhere outside the menu 
and click the lefthand mouse button. 
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To select an option from a menu, select the menu, then move the mouse pointer to 
the option required when it will be highlighted, then click. Don't select any options 
until you are using BASIC 2 for real; if you do, cancel them by selecting the [Cancel] 
exit button (if a Dialog box appears on the screen) or by pressing Ctrl-C. 

The options in each menu are described in detail in Appendix III 

Windows 

A window is simply a rectangular area of the screen used to display text or 
graphics. GEM allows you to have several windows on the screen at the same time, 
almost like having several separate screens. BASIC 2 uses each GEM window to 
provide a view of part of a larger underlying area, known as a virtual screen. 



Virtual screen 


Windows can be: 



moved around the screen 




scrolled - moved across 
the virtual screen to 
reveal a different part 































































Windows are independent of each other, but when two meet on the screen, one is 
considered to be in front of the other and it obscures your view of the overlapped 
part of the other 

BASIC 2 allows you to use up to four windows. All of these are placed on the 
display when you first select BASIC 2 Their size, position and behaviour are not 
fixed; these can be altered using the mouse and/or BASIC 2 commands. (The details 
of the various techniques for changing the size, moving and closing windows with 
the mouse will be given in your GEM user guide.) 

The four windows are called; 

Dialogue; This window is used for commands you want obeyed immediately - in 
particular, commands like RUN and EDIT If you want to use BASIC 2 as a simple 
calculator, you type commands like ? 42*1964 in the Dialogue window. This is 
known as using BASIC 2 in Direct Mode. 

Edit The Edit window shows the program you are working with and is used to 
change it If you type EDIT in the Dialogue window, you are automatically put into 
the Edit window so that you can start editing the program. 

Results- 1 and Results-2; These are used for output from your programs. BASIC 2 
is initially set up so that output is sent to the Results-1 window unless you 
specifically tell BASIC 2 to send it somewhere else. Both text and graphics can be 
sent to Results-1. Results-2 is initially hidden behind the Dialogue and Edit windows 
(you can see it if you move these windows away from the lefthand edge of the 
screen) but it is available if. say, you want to keep the text output from your 
program separate from the graphics output. (As Results-2 is set up. it can only be 
used for text.) 

Note: BASIC 2 may only put up three windows - Dialogue. Edit and Results-1. This 
indicates that there wasn’t enough memory available to put up the fourth window. If 
you need Results-2, reset your PC and load BASIC 2 again. 

Text and graphics 

BASIC 2 provides an enormous variety of graphics and text facilities. 

Select the Colour menu with your mouse to see the colours available for text and 
graphics. The current text and graphics colours are indicated in the menu with 
arrows. If you select the Patterns menu, you will see all the different patterns that 
are available for filling shapes that you draw on the screen. The Lines menu shows 
you the different styles, thicknesses and end-styles you can use when drawing lines. 

To see the text styles available, select the Fonts menu. This shows the available 
fonts (which have names like 'Swiss' and 'Dutch'), pitches and emphases (skewed, 
thickened, lightened and underlined). If an option is shown in light text, you cannot 
use it with the current font. 

We shall demonstrate the effects you can produce by selecting different options from 
these menus in Section 2.1. You can also use these effects from the BASIC 
commands you write by adding phrases like COLOUR n or FILL WITH n to the end 
of your commands. 
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Leaving BASIC 2 

When you have finished using BASIC 2 and want to use another GEM application, 
you should leave BASIC 2 and return to the GEM Desktop by selecting the Quit 
option from the File menu. 

If you haven’t saved the program you have been working with, you will be prompted 
that if you continue- you will lose it. If you want to keep it, first select the Save 
option in the File menu. This puts the Item Selector Dialog box on the screen: use 
this to specify which file you want to store the program in. 





2.1 A GUIDED TOUR OF BASIC 2 


This Section takes you on a guided tour of the facilities of BASIC 2. On this tour, 
you will be shown: 

- how to run a BASIC 2 program from the GEM Desktop 

- how to tell BASIC2 to draw a variety of shapes and fill these with different 
patterns 

- how to write messages on the screen in a range of different text sizes, styles, 
colours... 

- how to prepare a program and edit it - and what happens when there is 
something wrong with your program 

Don't worry if you don’t understand everything for now. This tour is just to give you 
the flavour of BASIC 2; the rest of the book will explain it in more detail. 

The first thing to do is to display the GEM Desktop. If you are not sure how to do 
this, consult your computer's user guide. 

Running a program from the Desktop 

All the BASIC 2 programs are supplied in the BASIC2 folder on your BASIC 2 disk, 
so work through this guided tour with a copy of this disk in your Drive A. 

The BASIC2 folder is in the Root directory of this disk (the AA directory), so start by 
showing this directory in one of your Desktop windows. You may need to click on 
the window's Close box (the ‘bow-tie’) a few times to work back to the Root 
directory from the folder you are currently working on. 

When you have the Root directory on the screen, move the pointer to the BASIC2 
folder icon. This should be near the top of the directory. When the pointer is on this 
icon, double-click the lefthand mouse button or click it once and then select the 
Open option from the File menu. 

When the new directory appears on the screen (the AABASIC2\ directory), move the 
pointer to the DEMO.BAS icon. When the pointer is on this icon, double-click the 
lefthand mouse button or click it once and then select the Open option from the File 
menu. 

After a short while, you will be able to see that your PC is loading the BASIC2.APP 
program and you will briefly see the initial BASIC 2 screen that we showed in 
Chapter 1. But if you look at the Dialogue window, you will see the command Run 
and then as you wait, you will see further activity both in the Edit window and in 
the Results-1 window. 

Watch what happens closely. What you are running is a special demonstration 
program that has been put together to show you the sort of commands you might 
use (shown in the Edit window) and the results these commands will have (in the 
Results-1 window). It demonstrates how just a few straightforward BASIC 2 
commands create some really attractive graphics. 
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When the program has finished, you will be asked whether you want to continue 
using BASIC 2 or whether you want to return to the GEM Desktop. Type Y 

You will now see the word Ready in the Dialogue box, followed by a cursor to show 
you that BASIC 2 is ready for you to type other commands. As we would like a clear 
Result s-1 screen for the next stage of the tour, type the command CLS and press 
□ED You will see the Results-1 window clear and once again you will see a 
Ready in the Dialogue window. 

Note that everything you type appears in the Dialogue window. This is because you 
are using BASIC 2 in its Direct Mode, ie. it is immediately processing every 
command you type in. 

Drawing circles, boxes, ellipses... 

BASIC 2 has a number of graphics commands, for drawing pictures on the screen, 
dot matrix printers, pen plotters, etc. A number of these were shown in the 
demonstration program. We shall now show how simple it is to draw these shapes 
for yourself. 

The commands all have names that reflect the type of shape you want to draw. To 
draw a circle you use a CIRCLE command; to draw a box you use the a BOX 
command; to plot a number of points you use the PLOT command. 

Try typing the command; 

CIRCLE 500;500, 300 H=H 

This draws a circle on the Results-1 screen with its centre at 500; 500 and radius 
300. These numbers are in 'user coordinates': user coordinates are specified in such 
a way that drawing shapes in the square Results-1 window you have on the screen 
when you start using BASIC 2 is very like drawing the same shapes on a square 
piece of graph paper with 5000 divisions on each side. Try altering the numbers 
used in the command to see how they affect the size and position of the circle 
drawn. 

The colour (or intensity, on a monochrome screen) and style of line used to draw the 
circle can be changed by using menu or command options. Select the Colour and 
Lines menus with your mouse to see which options are available. The colour and 
line style etc. that you have just used are marked with small arrows. 

Select a different colour (set a graphics colour because you will use it to draw 
graphics) and/or line style, then repeat the above command. The Lines menu lets 
you set the style of line, its thickness and the 'end-styles' short lines will have, but 
you will have to keep bringing the menu onto the screen because GEM closes up 
the menu after you make each selection. 

Another command to try is the BOX command. Try. for example, typing the 
command: 

BOX 300; 2500, 3000, 2000 l~m 

This draws a rectangle 3000 user coordinates wide, 2000 user coordinates high, with 
its bottom lefthand corner at 300:2500. Once again, you can use the Colour and Line 
menus to change the appearance of the rectangle. 

The next command to try is: 

CIRCLE 1000; 1000, 500 FILL l~P~l 







The first part of this command tells BASIC 2 to draw a circle centred at 1000; 1000 
and radius 500. The extra FILL tells it to fill the circle it draws. 

The pattern it uses to fill the circle is the one currently set in the Patterns menu. If 
you select this menu, you will see the range of patterns that are available: the one 
that has just been used is the one with the small arrow beside it. Select a different 
pattern and then type the command again, perhaps varying the position’ and radius 
of the circle. Or you can try replacing FILL with FILL WITH n. where n is a 
number between 0 and 38. 

Adding the word FILL to a BOX command or any of the other shape commands 
similarly tells BASIC 2 to draw the shape and then fill it with the selected pattern. 

Another change you can make to the BOX command is to add the word ROUNDED to 
the command. This draws a rectangle as before, but this time it gives it rounded 
corners. To see this, type a command like: 

BOX 300;200, 3000, 2000 FILL ROUNDED l~P~l 

Turtle graphics 

Another way to draw graphics is by moving a ‘turtle’ around the screen. The turtle 
is just a special form of pointer. 

To see a turtle in your Results-1 window, type: 

GRAPHICS CURSOR 3 |~P~1 
WINDOW CURSOR ON n=H 

If you have used the LOGO programming language, you will find many of BASIC 2's 
turtle graphics commands very familiar. For example, to draw a line of length 500 in 
the direction the turtle is pointing, type: 

FORWARD 500 

To turn the turtle's head, use the commands LEFT (anticlockwise) or RIGHT 
(clockwise), followed by an angle (usually in radians). For example: 

LEFT 1 H=H 

will turn the turtle 1 radian (approximately 60 degrees) anticlockwise. (If you prefer 
to work in degrees, select the Angles in. .. option in the Program menu and click 
on (Degrees] in the Dialog box that appears: then you could get a similar result by 
typing LEFT 60 n=H) 

Try using sequences of LEFT, RIGHT and FORWARD commands. (FORWARD can 
be shortened to FD; LEFT to LT; and RIGHT to RT.) Try using different line colours 
and styles, by selecting options from the Line and Colour menus. 

If you turn to the end of Part III, Chapter 5. you will find other turtle graphics 
commands you can try. 

When you have finished working with the turtle, turn its cursor off by typing: 

WINDOW CURSOR OFF ITH 
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Different ways of outputting text 

Type: 

PRINT "Text output" I *-> I 

This will simply print the text Text output’ in the Results-1 window. It will probably 
be printed using the standard ('System') text style. Once again, different colour and 
styles can be produced by using menu options. 

The colour is changed by setting a text colour through the Colour menu. The text 
style (or 'font'), the size of the characters and their emphasis (thickened, lightened, 
skewed or underlined) are changed through the Fonts menu. 

Select the Colour and Fonts menus and see what options are available. Try selecting 
a different text colour and a different font etc. It may take several selections of the 
Fonts menu to set the full combination of text style, character size and emphasis 
you want because GEM automatically closes up the menu as you make each 
selection. Again, you can also set all these effects by including special phrases in 
your BASIC commands. 

See what happens this time when you type: 

PRINT "Text output" |-P~t 

There is, by the way. a shorthand way of repeating your last command - type Ctrl-A 
(ie. hold down I cut I and press |A]) and then press I «-■ I 

Ybu can also display text in the other windows. For example, to display text in the 
Results-2 window, type: 

PRINT #2, "Text in the Results-2 window" | \ 

To start with, you won’t be able to see this text, but it is there! The Results-2 
window is initially hidden behind the Dialogue and Edit windows. To see it, move 
your mouse to the Dialogue window title bar, hold down the lefthand mouse button 
and drag the window down and to the right. 

If you compare this message with the last one you printed to the Results-1 window, 
you will see that they probably aren't the same colour and the font, character size 
and emphasis you set haven't been used for the Results-2 text. The reason for this is 
that the settings you have made in the menus only apply to the default screen - 
that is. the screen BASIC 2 sends output to unless you tell it otherwise 

To make Results-2 the default screen, type the command: 

stream #2 n=n 

After you have typed this command, pull down the menus one by one and see what 
effect changing the default screen has had. As you will see, the Lines and Patterns 
menus are now completely denuded and many of the Fonts options are no longer 
available. 

The reason for this is that Results-2 is a Text screen, whereas Results-1 was a 
Graphics screen. You can't draw any graphics on a text screen and you are limited 
to a fixed set of System characters to use for writing text. However, you can still set 
the colour the text is written in. 

When you want to return to using Results-1 as the default screen, type: 

STREAM #1 EE3 











Preparing a program 

To show how programs are prepared using BASIC 2, we shall now write a short 
BASIC program to draw a series of circles. 

As you have just been using another BASIC program, the demonstration program, 
start by pulling down the Program menu and selecting New. This clears the current 
program so that you can start work on another program - rather like selecting a 
fresh piece of paper to work on. 

Now bring the Edit menu onto the screen and select the Edit option. This 
automatically moves you to the Edit window. Anything you type now will appear in 
the Edit window. (You will see the command Edit appear in the Dialogue window 
as if you had typed this command yourself.) 

The program we are going to type is: 

FOR 1=1 TO 10 

CIRCLE 2500,2500,200*1 

NEXT 

END 

If you have programmed in BASIC before, you will immediately notice something 
about BASIC 2 - it doesn't need a line number at the beginning of each line (though 
you can put one in if you like). 

Type the lines in lower case, pressing | <-■ I at the end of each line. As you do this, 
you will notice various things happening: 

- Immediately you start typing and after you press l <•* i . a ♦ appears at the 
beginning of each program line. 

- As you finish each line, the command names are converted to upper case. This 
gives you a simple way of checking that you have typed the command names 
correctly, because if you had misspelt one it would be left in lower case. Similarly, 
if one of your variables gets converted to upper case, this means that you are 
trying to use a BASIC 2 keyword as a variable - which will make your program 
fail. 

To run the program, pull down the Edit menu and select Exit Edit. Then pull 
down the Program menu and select Run. You will see the command Run appear in 
the Dialogue window as if you had moved to this window and typed the command 
yourself. 

This will shortly be followed by Syntax error - because there was a deliberate 
mistake in the second line of program. The correct line is: 

CIRCLE 2500;2500,200*1 

Because an error has occurred, you have automatically been put back into the Edit 
window and the cursor is on the line that is wrong. 

Use the cursor keys to move to the 2 after the first comma, press I <o«i | to delete 
the comma, and type ; Then select Exit Edit and Run as before. The program 
should now run. 

You could now go on and change this program so that it does something mote 
exciting. Part III, Chapters 5-8 introduce you to the commands that are available in 
BASIC 2 and Appendix V gives the details. Just select Edit from the Edit menu to 
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start changing the program, and select Exi t Edi t and then Run to see the effect of 
your changes. 

If you want to save the program you create, pull down the File menu and select 
Save This saves your program as a simple text file. 

When you have finished using BASIC 2, pull down the File menu and select Quit. 
You will then be returned to the GEM Desktop. 



PART II: INTRODUCTION TO PROGRAMMING 


Read this part if you are new to computers or to BASIC 
programming. It will teach you how to begin programming using 
BASIC 2 and get you ready to use the more detailed description of 
BASIC 2 in Parts III and IV. 
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1. STARTING WITH BASIC 2 




This chapter will show you how to use BASIC 2 as a simple calculator. 

The only assumptions made are that you have read Part I of this guide and know 
how to work with GEM, using the keyboard and mouse (refer to your GEM guide if 
you do not). 

Read this while at your computer, after entering BASIC 2 (as described in Part I), so 
you can try put the facilities as you go. Don’t just sit there - do something! 

BASIC 2 as a calculator 

Although BASIC 2 is primarily a programming language ie, it is used to write and 
use programs, you can also use it more simply, as a sort of calculator. This is a lot 
easier to do (and explain) than starting to program straight away. 

Don't feel cheated, though (or fall asleep): using BASIC 2 in this way will introduce 
many of the fundamental concepts you will need to understand before you can 
begin to program. 

The rest of this chapter will introduce you to using BASIC 2 in this way. 
Programming with BASIC 2 is described in the following chapter. 

Giving instructions to BASIC 2 

BASIC 2 is a very powerful, willing servant, but it can't read your mind, so to get it 
to do something for you, you must first tell it what you want! 

The main way to do this is to type instructions. (You can also use the mouse to 
select GEM functions, or menu options, but these facilities are rather more limited''. 

These instructions must be expressed in the language that BASIC 2 understands. 
This language is called (you guessed it) ‘BASIC 2‘. Rather like a human language, 
this consists of two main elements: 

- vocabulary: the words that are the building bricks of the language, with their 
spellings and meanings 

- syntax: the rules that determine how words can be combined, and what the 
resulting combinations will mean 

The vocabulary of BASIC 2 is in two parts: a fixed list of words that BASIC 2 
already understands, called "BASIC 2 keywords' and extra words invented by the 
user, called 'identifiers'. 

Although keywords are not English words, most have been named to remind you of 
what they do, making them easier to remember and to spell correctly. For example, 
while you have not yet met keywords like PRINT, CIRCLE, COLOUR or STOP, you 
can probably guess the sorts of things they do. 
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Type: 


A full list of keywords is given in the appendices. They may be typed using capitals, 
small letters, or even a mixture of both! 

An instruction usually starts with a type of keyword called a 'command'. A 
command may be a complete instruction on its own: 


command 

A command may also be followed by information, known as its 'parameters': 
command parameters 

The parameters must be separated from the command by one or more spaces. 

A command is rather like a verb in an English sentence: it indicates the action 
required. There are a wide variety of commands, representative examples of which 
will be introduced over the next few chapters. 

One of the simplest commands to understand is PRINT. PRINT simply tells BASIC 2 
to display the information contained in the rest of the instruction - to 'print' it on 
the screen. 

The parameters part of an instruction is rather like the object in an English 
sentence: it tells the computer what to do the command to or with. In the case of 
PRINT, it tells the computer what to print. 

Thus, to tell BASIC 2 to print the number 42 on the screen: 


PRINT 42 

W-'V' 

| parameter 

command 


an instruction 


Try this now. That is, type PRINT 42 and press 1 <-■ I . Remember to leave a space 
between the T and the 4. See how what you type is displayed as you type it, in the 
Dialogue window. Nothing else happens until you press I «-■ I , when BASIC 2 
obeys the command: it prints the information, in the Results window. 

Note that BASIC 2 does not try to obey the instruction as you type it. but when you 
press I «-» I : up until then, you are free to alter what you have typed, by deleting it 
with I -<o»t I and retyping. 

You may find this rather useful, particularly at the start, when everything is new and 
typing errors are inevitable. For, despite its great flexibility and power, BASIC 2 is 
rather formal and insists on exact spelling and syntax in instructions! 

Misspelt commands will normally produce a mild rebuff from BASIC 2 in the form of 
an short message in the Dialogue window, such as 'Syntax Error", with the 
instruction otherwise being ignored. These messages are called error messages. 

An error message indicates that BASIC 2 has encountered something it can't cope 
with and is giving up. The content of the message indicates the reason for the 
failure. This is very useful when developing programs, but for now, if you get an 
unexpected message of this sort, just check your typing and try again. 













PRINT can also print more than one parameter, by separating them with semicolons 
- the parameters will then be displayed immediately after one another. For example: 

Type: PRINT 42;43 I~P~1 

42 43 

Another simple command is CLS, which 'wipes’ the window being used for output: 
Type: CLSQD 

Finally, the command DIR is used to list the names of all files on a disc (the current 
drive and directory): 

Type: DIRKED 

(You may notice that the names are listed in the Dialogue window, not the Results 
window. Ignore this for now.) 

Types of command 

BASIC 2 provides a very wide range of commands, to take much of the hard work 
out of solving problems. Representative examples will be introduced gradually 
throughout the rest of this part. The commands available are described in a rather 
more thorough manner in Parts in and IV! 

Types of information 

The information part of an instruction can take a wide variety of forms, as follows. 
While initially confusing, it is this type of versatility that, once mastered, makes 
programming languages so adaptable. 


Fixed information (constants) 

The simplest type of information to understand is that already used in the PRINT 
example above: 


PRINT 42 n=n 

Vv 

| constant (number) 
command 


In this instruction, a number has been specified by typing it in the instruction. This 
type of information is called a 'constant' (or 'literal'), because its value is fixed and 
obvious from the instruction. There are two types of constants: numbers (such as 
42, 0.0000002, -11111111111) and ‘text strings’ (such as “Hello". “Returns for tax 
year 84/5", "42”): 


Type: ^PRINT^ " Hello, gentle reader " ! - * 3 "! 
command constant (text string) 

Note that a text string ('string' for short) always starts with and ends with a double 
quote character ("). 
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Varying information (variables) 


The second type of information is called a 'variable'. A variable is a name for an 
item of information rather than the information itself. When BASIC 2 obeys an 
instruction containing a variable, it substitutes for the variable the information that it 
has previously stored for that name. 

A variable works in quite a different way to a constant. When a constant is used, 
the information is obvious from the instruction. When a variable is used, you cannot 
tell exactly what the information it represents is! 

But why use a variable instead of the constant value that you want in the 
instruction? 

By using a variable, you make the instruction versatile - by changing the value 
stored for the variable, you can use the same instruction over and over, rather than 
have a different instruction for each value. Variables can also provide a convenient 
shorthand for awkward constants, such as used in metric to imperial conversion. 

There are two types of variable, used to store the two different types of information: 
numeric (numbers) and string (text). 

Numeric variables have names that start with any letter, followed by any letters or 
numbers. String variables can have identical names, except that the last character of 
the name must be '$’. (This is not the whole story; we will return to naming later.) 

Note that although you can use small or capital letters in variable names, they are 
considered as identical by BASIC 2. For example, 'cat', 'Cat' and 'CAT' are all the 
same variable, even though they look quite different. 

When it displays a stored program, BASIC 2 shows keywords in capitals and 
variables in small letters, to help you distinguish them. The same convention will be 
used throughout this guide. 

Typical variable names are as follows: 

numeric: 

a, count/ vatrate 
string: 

a$/ nameS, address$ 

You are free to choose variable names with only a few limitations, the most 
significant of which is that a variable name must not be the same as a BASIC 2 
keyword (as listed in Appendix IV). 

A variable can in general be used anywhere that you could use a similar constant. 

So much for using variables and naming them, but where does the variable get its 
value from? The main way to give a value to a variable is to 'assign' the value to it, 
using the equals sign (=), in an assignment instruction. This is also called 'defining' 
the variable 

For example, to give the variable 'vat' a value of 0.15, you could: 


Type: vat = 0.15 1 <-> I 

variable 

assigned value 




You could then use this variable whenever you wanted the value 0.15. For example: 
Type: PRINT | g | 

^variable 
command 

Similarly, after defining a string variable, such as name$: 

Type: name$ = "Anne Elizabeth Barnard" f ^ I 

You could print this name easily and quickly, using: 

Type: PRINT name$| I 

y variable 
command 

Note that the result of using a variable in this instruction is exactly the same as 
using a constant with the same value: it is simply more convenient. 

The value of a variable is defined or changed, but never fixed by assigning to it: 
you can change its value as many times as you like. When the variable is used in an 
instruction, its value will be the value most recently assigned to it, 

(You may have been surprised at the form of the assignment instruction. Where is 
the command that is supposed to start each instruction, telling BASIC 2 what you 
want it to do? The answer is that BASIC 2 analyses the instruction, sees the equals 
sign and interprets the instruction as if there were an invisible assignment command 
at its start! You can in fact use the assignment command, LET, but there is no need 
to do so.) 


Calculated information (expressions) 

The third type of information which can be used in an instruction is an 'expression'. 
An expression is a sort of 'recipe', that BASIC 2 has to ‘cook’ (evaluate) to produce 
the result which will then be used as the instruction's parameter. 

An expression consists of constants and/or variables, combined by 'operators' 
and/or 'functions'. Operators and functions instruct BASIC 2 just how to manipulate 
the other information to produce the result, as follows. 

Operators 

Operators are single symbols (or keywords), used between two items of information, 
producing a single result which is derived from them both. 

The simplest expressions to understand use the familiar operators for addition and 
subtraction: + and -. Try the following instructions to see them in action: 

Type: PRINT 42>5 n=H 
operator 

v—— V - ' J 

expression 


and 
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I § I 


Type: PRINT 42-3[“^n 
- 

expression 

In these instructions, you see the result of the expression, because it is displayed on 
the screen by the PRINT command. Note that an expression is not a command - it 
only produces an item of information, for use in a command. 

Two other highly useful operators are for multiplication (*) and division (/). While 
the symbols used may not be familiar, their actions should be. Try the following: 

Type: PRINT 42»3 n=H 

expression 


and 



expression 


Note how the division symbol comes after the number to be divided, but before the 
number to divide with. (Think of the symbol as 'divided by', so the division 
expression is '42 divided by 3'.) 

These four operators will work quite happily with any combination of numeric 
constants and variables. The expressions produced are called ‘numeric expressions', 
because the result produced is numeric. Feel free to invent and try out similar 
expressions in PRINT instructions, using these four operators. 

There is only one operator that will work with strings: +. While this is the same 
symbol as used to add numbers in a numeric expression, it has a different effect 
when used with strings - it adds one string onto the end of the other. Type the 
following exactly as shown, but before pressing I g I for the third time, try to 
predict what will happen. 

first* = "niicro" rP~l 


lasts = "computer" ! ^ I 


PRINT v firstS+LastSrP-l 

expression 
Were you right? 

To see the difference between adding numbers and strings, compare the results of 
the following two commands: 


Type: PRINT 42+43QD 

numeric expression 


Type: PRINT "42"+ ,, 43 ,, n=n 

string expression 

In the numeric expression, the numbers are added together to produce a result 
which is their arithmetic total, 85. In the string expression, the second string is 
stuck onto the end of the first to produce the string ''4243”. 

















Finally, try: 

Type: PRINT 42+"45" n=H 

BASIC 2 objects to this expression, because the two items being manipulated are 
not compatible - an expression must consist of all numeric or all string items. 

Functions 

A function is a BASIC 2 keyword that is followed by one or more items of 
information in round brackets: ( and ). These items of information are usually called 
the function's 'arguments'. When a function is used, its arguments are evaluated to 
produce a single result, rather like an expression. 

A typical function is SQR (SQuare Root), which produces the square root of its 
argument: 

Type: number = 121 

Type: PRINT SQR(number) |~P~| 

11 

SQR is an example of a numeric function: a function that produces a numeric result. 

There are also a variety of string functions: functions that produce a string result. 

A typical string function is UPPERS, which converts all alphabetical characters in its 
string argument into the equivalent capitals. For example, to print the contents of 
the variable 'nameS' (defined previously) as capitals: 

Type: PRINT UPPERS(nameS) 

ANNE ELIZABETH BARNARD 

If a function has more than one argument, they are separated by commas. 

While string functions normally have string arguments and numeric functions 
normally have numeric arguments, some functions use information of one type but 
produce information of the other type. For example, to tell how long ‘nameS’ is, 
instead of printing it then counting the number of characters yourself, let BASIC 2 
do it for you: 

Type: PRINT LEN(nameS) 

22 

Such functions are still classified as string or numeric according to the type of result 
they produce, so LEN is a numeric function. 

BASIC 2 provides a very wide variety of functions that calculate cosines or 
logarithms, extract text from the middle of strings, convert a string to capitals, a 
string to a number, a number to a hexadecimal string, etc. These are described in 
further detail in Part III. (You can even define and use your own functions, within a 
program!) 

More complex expressions 

The expressions given as examples so far have been quite simple, with each using 
only two items of information (constants or variables) and a single operator. 
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Expressions need not be this simple. For example, to add 22, 44 and 90000032 then 
take 400311 from the result, you could use three separate instructions: 

Type: PRINT 22 + 44 rP~] 

66 

Type: PRINT 66+90000032GED 

00000009 

7MWWD70 

Type: PRINT 90000098-400311 
89599787 

However, you can combine these three expressions into one and get the answer by 
typing the single instruction: 

Type: PRINT 22+44+90000032-400311 H=H 

89599787 

(You can make expressions as complex as you wish. The only limit is that no line 
can be more than 255 characters long.) 

Try this yourself now. using any of the arithmetic operators with numeric constants. 

Were you surprised at any of the answers displayed for your own calculations? Once 
an expression contains more than one operator it may not be obvious how it will be 
evaluated. This is because the order in which the operators are applied can alter the 
result. 

For instance, 

3 + 4*5 

could be calculated as: 

3 + 4 = 7 

* 5 = 35 

or as: 

3 + 

4 * 5 = 20 

= 23 

BASIC 2 has rules about the way in which operators work in combination, called 
'operator precedence'. For example. * and / are applied to the information to each 
side of them before + and -, so that 3+4*5 is evaluated as '4 times 5, plus 3’. 
Parts of the expression involving * and / are evaluated in order from left to right, 
then parts involving + and -, again from left to right. 

Operator precedence is described fully in Part III. For now, just put round brackets 
around any part of a complex expression that you want to be evaluated separately. 
This will then be evaluated to a result which will be used in the rest of the 
expression. 

For example (3+4) *5 will be evaluated as (7) *5, while 3+(4*5) will be evaluated as 
3+(20). 



- 


You can also use functions within expressions. They behave exactly as single 
numeric or string values, depending on the type of function. For example, to print 
the sum of the square roots of 'sidex' and 'sidey': 

Type: PRINT SQR(sidex) + SQR(sidey)[^J 

You can also use expressions as a function's arguments. For example, to print the 
total length of 'name$' and 'addressS': 

Type: PRINT LEN(name$+address$) | «-< | 


Chapter review 

In this chapter, you have learned that BASIC 2 instructions consist of commands 
and information, known as its parameters. 

You have also learned about the basic types of information: numeric and string 
constants, variables and expressions. 

Finally, you have learned how to make BASIC 2 perform simple tasks like 
calculating and displaying sums. 

Using the information covered here, attempt the following tasks: 

1 Identify which group each of the following belongs to: 


Command Numeric String Numeric String Expression 

constant constant variable variable 


PRINT 

name$ 

SQR(10) 

1234 

1234.1 

sub.tota 1*10 


2 Give the variable 'totall' a value of 100, 'total2' a value of 150, then display their 
sum 

3 Make BASIC 2 add the two numbers 22 and 33 and display the result. Now do the 
same usi ng the strings "22" and "33". Predict what the result will look like before 
pressing l *-> I Do you understand the different effect of '+* in the two 
expressions? 
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Solutions 


1 


Command Numeric String Numeric String Expression 

constant constant variable variable 


PRINT / 

names 

SQR(10) 

1234 / 

1234.1 / 

sub-tota1*10 


/ 

/ 


2 

Type: totall = 100 1 <-* I 
Type: total2 = 150 1 *-> I 


Type: PRINT total1+total2 | <-■ I 


3 

Type: 22*33 1 g 1 


Type: "22"+"33"CEJ 

The first result, 55, is the arithmetic sum of 22 and 33. The second result, 2233 is 
the result of appending the string "33" to "22". The results are different because the 
expressions are of different types! 






2. SIMPLE PROGRAMMING 


This chapter will show you how to start writing BASIC 2 programs and introduce 
more fundamental concepts. It will also show you how to use some of the tools that 
BASIC 2 provides to make writing and using programs easier. 

A first program 

So far, although you have learned how to use a number of BASIC 2 facilities, you 
have not written or even used a BASIC 2 program. This can soon be put right. 

First, you must tell BASIC 2 that you want to write a program from scratch. Either 
use the command NEW: 

NEW r~P~l 

or use the 'New' option in the Program menu: click on the Program menu bar to 
display the options, then click on the 'New' option. 

(While this is not essential, it tells BASIC 2 to clear away any rubbish it might have 
in its program memory, and is a good habit to get into.) 

Now, you must leave the Dialogue window (where you have been typing 
commands) and enter the Edit window (where you can write programs). There are a 
number of ways to do this. If the Edit window is visible, simply click on it. If not, 
use the command EDIT: 

EDIT I~P~I 

You are now in the Edit window. Now, type the following: 

PRINT 42 n=n 

You have now written your first program! 

While in the Edit window, anything you type will be stored, as a program! This is 
quite unlike the Dialogue window, where anything you type will be interpreted as a 
command, which BASIC 2 will attempt to obey immediately. The edit window also 
gives you access to a number of facilities which make typing or changing the 
program easier. More of this shortly! 

To move back to the Dialogue window, all you need do is click in it. 

Your first program consists of a single line, with a single instruction (PRINT - the 
first one you met, in chapter 1). Instructions in a program are more usually called 
'statements', which helps distinguish them from instructions that are obeyed 
immediately they are typed. This terminology will be used in the rest of this guide. 

A program is simply one or more BASIC 2 statements, stored by BASIC 2 because 
they were typed in the Edit window. 

The program that BASIC 2 has stored in memory is called the ‘current program'. 
This is the program that you have most convenient access to. For example, it is the 
current program that is displayed in the Edit window and that can be obeyed or 
changed most easily. 
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You can only have one current program at a time, but can easily make a different 
program the current program, for example by typing it or reading it from a disc. 

So how is this program different from the statement PRINT 42 | *■> | ? A program 
has two main extra properties: 

- it can be used over and over again without having to retype it each time 

- it can be stored (on a disc) for later use, for example after the computer has been 
turned off and on again 

Using and storing programs 

As stated above, a program is not obeyed when you type it. To make BASIC 2 obey 
('run') the current program (ie the one you've just typed), you can either select the 
option 'run' from the Program menu, or type the BASIC 2 command RUN in the 
Dialogue window. 

Try each now. (Remember that to return to the Dialogue window, you simply need 
to click in it.) Is there any difference in the result? 

Your simple program should simply print “42'' each time it is run. If you get some 
other message, there is an error in your program. Start again with NEW etc and be 
more careful with your typing this time! 

You can run the cunent program over and over again, unless you lose it. The 
current program is lost if, for example, you leave BASIC 2. turn the computer off. or 
use 'New'. 

To keep the current program safe, you can store it on a disc, using the 'Save ...’ 
option in the File menu. (You will need a disc which is not write-protected for this.) 
Programs are stored on the disc as separate named entities called 'files': you tell 
BASIC 2 what name to use for the program file in reply to a prompt. 

The file can be called any name that is valid for the computer's operating system 
(refer to the other guides supplied with your computer). It is simplest to stick to file 
names of up to 8 alphabetic/numeric characters (A to Z, a to z and 0 to 9), as many 
other characters have special meanings in names - for example, a '.' is used to 
specify the filetype and in directory naming. 

Saving the current program does not remove it from memory, it simply puts a copy 
of it on the disc, so you can continue to use it as if you had not saved it. 

To use a program from the disc, you must first load it from the disc, using the 
‘Load...’ option in the File menu. This makes it the current program, so you can run 
it using the RUN command or menu option. 

Once a program has been read from the disc, it becomes the current program, 
replacing any previous one. You can then re-use it over and over again; you do not 
have to read it from the disc again each time. The name of the program is shown as 
the title of the Edit window. 

If you are a real sceptic you can prove that this second version of RUN really works, 
by turning the computer off and then on again, restarting GEM and BASIC 2 and 
only then using the RUN command. This level of scepticism could prove rather 
inconvenient, though! If you really must do this, remember to remove the disc(s) 
from the drives first. 
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If you examine the disc now, using the command DIR, you will notice that the 
program is stored as a file with the name you specified plus a suffix of '.BAS’. This 
suffix identifies the file as a BASIC 2 program. 

Program structure 

As soon as a program consists of more than one line (and most do!), the order in 
which its lines will be obeyed becomes important. This order is dictated, at the 
simplest level, by the order of lines within the program. 

For example, the following three-line program works correctly: 

PRINT "64 times 64" 

PRINT "Is" 

PRINT 64*64 

Run it and see: 

64 times 64 
Is 

4096 

While the following, consisting of the same three lines, but in a different order, 
produces a rather less positive result! 

PRINT "Is" 

PRINT "64 times 64" 

PRINT 64*64 

Run it and see: 

Is 

64 times 64 
4096 

As described above, a program line con sists o f three parts: a command, any 
parameters used by that command, and a l «-■ l character, to finish the line: 

command parameters I <- J I 
v_ y. _ ' 

a statement end of line 

In fact, there are two further optional refinements: line numbers and multi-statement 
lines. 

A line-number is a decimal number (without fractional part) which, if used, must be 
placed at the start of the program line. It can then be used to refer to that line, 
within the program (more of this later: see GOTO). 

Note that a line-number has no effect whatsoever on its positioning within a 
program! This may come as a great surprise if you have used a line 
number-oriented language, such as most earlier versions of BASIC. 
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A multi-statement line is a line consisting of two or more statements, separated by 
colons. Statements within such a line are obeyed in the order in which you would 
read them ie left to right. Thus, the preceding example program could be written 
using one line rather than three: 

PRINT "64 times 64":PRINT"is: ,, :PRINT 64*64 

'-»- * '-V--V-' 

first statement third statement 

second statement 

(A long line may in fact be displayed over several lines - this has no effect on how i 
is stored or obeyed.) 

There are occasions when multi-statement lines are very useful, but for now stick U 
a single statement per line. This makes programs easier to write, understand ant 
change. 

Preparing programs 

Programs are typed and changed in the Edit window, which provides a number c 
facilities to help you, as follows. 

You will probably find the Edit window easier to use if you increase its size, eg b 
clicking its "full size’ box. 



Typing programs 

Text i s normally insert ed as you type it and can be corrected by deleting usin« 
|«o* 1 . When you press I <-■ l that signals the end of a program line and moves th 
cursor to the start of the next line. If the line you are typing is longer than the ed: 
window's w idth, ju st keep typing and it will be continued on the next screen line 
don't press I <-» I . except to end the program line. 

If you want to repeat a character, you can simply hold down the key and after 
short delay, it will 'repeat' itself. 
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Program lines are positioned within the program exactly where you type them. 
Thus, if you simply type each line in turn, starting with the first and ending each 
with | <-* | . they will automatically be in the right order. (This order is important, 
since it dictates the order in which the lines will be obeyed.) 

If you spot an error soon after typing it. you can just correct it by deleting back to it 
using |«oi I , then retyping the correct version. 

But what if you want to correct a line, typed several lines ago. or insert another line 
near the start? While it would be possible to do this by deleting back to the error, it 
would be laborious and heart-breaking. 

Altering programs 

You can alter any part of the current program, rather than what you've just typed, 
by simply moving the cursor to where you want to make the change, then getting 
on with it. For example, to insert another line at the start of the program, you would 
move the cursor to the start of the program and start typing. 

The cursor is moved as follows: 

1 | To move the cursor a line or character at a time, use the cursor keys. Note that the 

1 | cursor I <- | key is distinct from I -*o«< I . which deletes characters. Remember that 

^~| the cursor keys will 'repeat' if held down. 


To move the cursor more quickly, point to the required destination with the mouse 
and click - the cursor will jump straight to that position. 

| Homa~l To move to the start of the program, press I Hom» I 

[ 6nd~ | To move to the end of the program, press I end I . 

If the program is too long to fit into the Edit window, it will scroll whenever the text 
cursor attempts to move beyond the top or bottom of the window, to reveal more of 
the program. You can also scroll the window directly, using the mouse and the 
window's scroller. 

Once the cursor is positioned where you want to make changes, you have three 
main options: to insert, delete or replace text: 

• To insert text at the cursor, simply keep typing. 

• To replace text at the cursor, either press I in. | . or select the ‘Insert off option 
in the Edit menu. Characters you t ype su bsequently will replace ('overtype') 
characters at the cursor, until you press I h» I again or select the 'Insert on' option, 
which returns you to inserting. 

• To de lete text, either use l«o«i I . to delete characters to the left of the cursor, or 
I o>» I to delete the character at the cursor (and then, to its right). 

Of course, the most drastic way to change the current program is to delete it all 
(using the option or command. NEW) or replace it all (using the option 'Load'), as 
described previously. 

You can also delete, move, or copy parts of a program. See Part III for details. 
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Examining programs 

To examine a program, you must first make it the current program (eg by loading it 
from disc, using a File menu option). You can then view it in the Edit window, 
scrolling up and down through the program, using the window scroller and mouse 
or using the cursor and other keys, as described above. 

You can also produce a printed copy of the current program, by using the 'List' 
option in the Program menu. 

Chapter review 

In this chapter you have learned how to create programs from the commands and 
types of information introduced in the previous chapter. You have also learned how 
to store programs on a disc and re-use them. Finally, you have learned how to 
examine and change a program. 

1 Which of the following is a usable program? (HINT: type each in and try to RUN it) 

a vat=0.15 

cost=100 _ 

PRINT "VAT to pay;":vat»cost n=n 

b 10 vat=0.15 | <-■ 

20 cost=100 | t- 1 _ 

30 PRINT "VAT to pay :"n=H 
40 PRINT vat*cost r~^H 

c vat=0.15 n=H _ 

PRINT "VAT to pay:"n=n 
PRINT va t»cos t [-P~l 
cost=100 l g I 

2 Type the following program, exactly as shown. 

CLS 

cats = 10 
mouse = 42 
rats = 28 
PRINT "There are" 

PRINT cats/mouse+rats 
PRINT "rodents per cat" 

PRINT "the mice will play" 

PRINT "Still, while the cat's away" 

Now make the following corrections: 

- Correct the calculation 

- Change ‘mouse* to 'mice' throughout 

- Correct the ‘well known saying’ by swapping lines 

Run the program to check that it is now correct. 

3 Which of the following will change or delete- the current program? 

a turning the computer off 










b selecting, then closing the Edit window 
c typing NEW l <-» I in the Dialogue window 
d typing NEW ! ^ | in the Edit window 
e using the ‘Save’ option in the File menu 
f using the 'Load' option in the File menu 
g typing RUN l ^ l in the Dialogue window 
h typing PRINT "Hi!" ! I in the Dialogue window 


Solutions 

1 Versions a and b are equivalent, because line numbers are optional and do not 
impose any ordering, c is not sensible, because it uses the variable ‘cost’ (in the 
PRINT statement) before assigning a value to it (in the last line). 

2 The program, after correction, should look like this: 

CLS 

cats = 10 
mice = 42 
rats = 28 
PRINT "There are" 

PRINT <mice+rats)/cats 
PRINT "rodents per cat" 

PRINT "Still, while the cat's away" 

PRINT "the mice will play" 

When run, it should display the following: 

There are 
7 

rodents per cat 

Still, while the cat's away 

the mice will play 

3 The following change the current program: 

a - loses the program and BASIC 2 from memory! 
c - deletes the current program 

d - inserts the line 'NEW' in the current program, changing it 
f - replaces the current program with another program, from the disc 
The following do not: 

b - simply removes the Edit window from the screen, without changing its contents 
e - saves a copy of the current program on disk 
g - executes the current program 

h - executes the command, which does not change the current program 
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3. DESIGNING SIMPLE PROGRAMS 


As described in the previous chapter, a computer program is simply a collection of 
instructions that the computer has stored, to tell it how to perform a task. 

The programs that you have seen or written yourself in the previous chapter have all 
been quite simple, using only a handful of the facilities available. Unfortunately, such 
simple programs can generally only solve simple problems. This chapter describes 
how to use a wider range of facilities, to produce rather more powerful programs 
that can solve more complex problems. 

To make the best use of this growing range of facilities (and indeed to master the 
more complex tasks you will be able to undertake using them) will require a rather 
more deliberate approach, but you should find this extra effort well worthwhile. 

Programming 

Developing even the simplest program from 'nothing' involves a number of steps. A 
typical breakdown of the activities involved in producing a fairly complex program 
that will be used for an important task might be as follows: 

- deciding what you want the program to achieve (task analysis) 

- deciding how the program should achieve what you want (detail design) 

- preparing the program (coding) 

- checking that the program works correctly (testing) 

- writing instructions for the user (documentation) 

- correcting errors in and improving the program while it is being used 
(maintenance) 

The amount of effort given to each step varies enormously with the complexity of 
the task and program. These activities will be re-examined in greater detail in later 
chapters. For now, the most important thing to realise is that you should always 
start to think about what the program will have to do (analysis and design) before 
you begin to write (code) it! 

Analysis 

Analysis of the task is important, if only to make sure you're writing a program for 
the right task! It’s no good writing a program to count the number of words in a 
document, if the user wants to count the number of sentences. 

For a typical small program, this analysis would usually be no more than one or two 
carefully thought out paragraphs, using terms familiar to the user. 

For example: 

- 'calculate and print VAT returns from VAT-inclusive receipts and payments, 
typed by the user at the end of each VAT quarter' 
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Design 


The purpose of the design stage is to convert the description of what the program 
should achieve (expressed in the user’s terms) into a detailed specification of how 
the program should do it, expressed using the terms of the programmer. 

Rather than try to design the whole program in one go, split the task into smaller, 
more manageable stages and design those. You will need somewhere between 2 
and about 20 of these, depending on how complex the task is. 

Analyse each stage in turn, describing it simply, using a phrase or two. 

For example, if the task were to keep your personal accounts, the task description 
might be: 

produce personal accounts in the form of current balance from transactions typed 
by the user 

The most obvious stages in this task might be: 

get.a transaction (debit/credit) from the user 
perform the calculations required to adjust the balance 
display the resulting balance 

This 'core' of three stages would be repeated over and over again until the user has 
entered all the transactions, at which point the program would finish. 

Is this all? At the start of the program, you might want to be able to type in the 
current balance or read it from disc; in the latter case, at the end of the program you 
would also want to store the current balance, for use next time. A better description 
would thus be: 

get the previous balance from disc 
repeat: 

get a transaction (debit/credit) from the user 
perform the calculations required to adjust the balance 
print the resulting balance on the screen 
until finished 

save the current balance to disc 

(Note that to produce these stages, you need to have a general idea of the types of 
things BASIC 2 can do for you, without going into the details of how it does it. 
More of this later.) 

Specification 

You are now ready to translate each stage in the task into a detailed specification of 
the individual steps that the computer must take to perform it, using the words and 
concepts that the programming language provides. 

To do this, you need to know quite a lot about the programming language. 
BASIC 2. In particular, the kinds of things that it can and cannot do. It is no good 
specifying a step like ’total all the subtotals’ if the language doesn't provide any 
arithmetic facilities! (BASIC 2 does, of course, but some languages do not!) 



M 



One way to reach the happy position of knowing all about the facilities available is 
to plough on and learn about each and every facility before trying to write another 
program! This would be slow, terribly dull and probably doomed to failure. 

How then? At first (or even second) glance, the total number of facilities and 
keywords provided by BASIC 2 would probably seem quite overwhelming. How will 
you ever make sense of them all? The real answer is that you don’t need to make 
sense of them all, just yet. This part of the guide has been designed to allow you to 
read it in sequence, introducing facilities gradually and in context. This should make 
it easy for you to make steady progress by reading, doing the exercises and 
experimenting. 

To help you grasp the range of facilities provided by BASIC 2, its keywords are 
grouped into classes. Each class contains all the facilities concerned with a 
particular function, such as calculating or displaying text. Once you know and 
understand these classifications, you'll find you can quickly survey the facilities 
provided in a particular area, or home in on the particular keyword that does what 
you want. BASIC 2 is a rich and versatile programming language; you should rarely 
fail to find a suitable keyword. 

There are probably as many ways of classifying keywords as there are people who 
try to do so, but the following classification is used in this guide. 

Classes of keyword 

All programs take information, manipulate it in some way, then use the manipulated 
information to produce results. One of the simplest ways of breaking down a task, 
then, is to consider it as these three stages; 

- obtaining the information; ’input' 

- manipulating the information; ’processing’ 

- using the manipulated information; 'output' 

(See if you can recognise these three phases in the analysis of the accounting task, 
above.) 

These three phases in performing a task each have their own keywords, so the first 
three classes of keyword are input, processing and output. 

Examples of processing keywords that you have already met are the arithmetic 
operators (+-*/) and the functions SQR and UPPERS. An example of an output 
keyword is PRINT. You have not yet met an example of an input keyword. 

There are two more classes of keyword-. 

The fourth class has been hinted at already, in the example personal accounts task 
described above. This class is concerned with controlling input, processing and 
output, to produce repetition, structuring, logical decisions etc. You have not met 
any members of this class yet. 

The fifth class of keyword comprises the program development keywords, mainly 
commands, that make life easier while developing, testing and running programs - 
unlike the other four classes, they are not much used within programs. Examples 
you have already met are NEW, RUN and EDIT. (There are also many more program 
development facilities available using menus and the mouse.) 
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The five main classes of keyword that you will meet within this guide are thus: 

- input 

- processing 

- output 

- control 

- development tools 

Program development tools were described in the previous chapter. The other four 
classes will now be surveyed in the next four chapters, describing a representative 
selection of the keywords in each and showing them in action. At the same time, 
any important related concepts will be introduced or revised. 

These classes are also used as the main structure of Part III. 

(There are a number of keywords that do not fit this classification neatly. In 
particular, disc commands such as DIR, which obtain information (input) and then 
display it (output). These will be classifed according to their main use.) 

Facilities available 

The types of facility provided by each class are as follows: 

• Input: taking information from the keyboard, mouse, or discs 

• Processing numbers: arithmetic, trigonometric and scientific functions, random 
numbers, converting strings to numbers 

• Processing text: extracting text from within strings, generating strings, converting 
between capitals and small letters, searching strings, converting numbers to strings 

• Output: displaying text and numbers and controlling format, style and position, 
controlling screen windows, drawing pictures, storing information on disc 

• Control: making choices, repeating instructions, compartmenting programs, defining 
extra ‘commands’ and ‘functions' 

• Development: using and editing programs, examining discs (menus give access to 
many more facilities) 

Exercises in design 

1 The task is to request users’ names and when finished, print a list in alphabetical 
order. Break this down into stages (don’t worry how the information will be 
processed). 

2 Which of the following process information? 

a operators 
b functions 
c string expressions 
d variables 
e PRINT 
f NEW 




3 The following stages have been (correctly!) deduced from a task specification to 
draw pictures from typed commands. They are however in the wrong order - what 
is the right order? 

a draw graphics element 

b request and store graphics command 

c repeat 

d clear screen 

e until finished 

4 Classify the following into input/process/output/control/development keywords: 
a PRINT 

b count = 2* count 
c EDIT 

d PRINT count 

Solutions 

1 repeat 

get and store next name 
until finished 

process names into alphabetical list 
repeat 

print next name in alphabetical list 
until finished 

2 Items a, b and c process information. Variables are only used to store information, 
which may be used in processing. PRINT is used to output. NEW is used to develop 
programs. 

3 The order is d, c. b, a. e: 

clear screen 
repeat 

request and store graphics command 
draw graphics element 
until finished 

4 Only a and d are output; b is processing, c is program development. 
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4. INPUT, INFORMATION AND VARIABLES 


This chapter describes the types of information that a program can use and how it 
obtains and holds it ie: 

- information types (numbers and text) 

- information sources (input) 

- information storage (variables) 


Types of information 


As far as BASIC 2 is concerned, there are only two types of information: numbers 
(numeric information) and text (string information). In general, these two types are 
quite distinct and incompatible, having different behaviour and keywords associated 
with them. 

Numbers 

When typing numbers for BASIC 2 to use, you can use a variety of forms, as 
follows. 

The most familiar numbers are what are known as 'unsealed numbers': integers and 
decimal numbers. 

Integers are 'counting numbers' or 'whole numbers’ ie numbers without a fractional 
part. For example: 

—44444 


integer 

0 

V' 

integer 

Decimals are numbers with a (decimal) fractional part, such as: 


3.111 



| fractional part 
integer 

-0.00077702 

'-V-' 

fractional part 

This is the form of numbers that you are probably most familiar with and will use for 
most of the time in programs. 

Note that you cannot type numbers with commas in them. 

Numbers can start with a + or - sign. A - makes the number negative. A number 
starting without a sign, or with a + sign is positive. 
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BASIC 2 can handle numbers in an enormous range, from the very large to the vers 
small. Thus, it can handle almost any number that you might want to specify. 

The largest number it can handle normally is about 100 million million million million 
million million (ie 10 38 ): 

100 , 000 , 000 , 000 , 000 , 000 , 000 , 000 , 000 , 000 , 000 , 000,000 

(Remember that the commas are included here just to help you read the number. II 
you typed this number for BASIC 2 to use. you could not use commas.) 

The smallest number it can handle normally (that it is distinct from 0) is about 1 
divided by the same very large number (ie 10 38 ): 

1 

100 , 000 , 000 , 000 , 000 , 000 , 000 , 000 , 000 , 000 , 000 , 000,000 

Numbers are stored with a fixed maximum accuracy, or 'precision' of nine decimal 
digits. Again, you are unlikely to find this a limitation. See Part III for details. 

If you want to type very large or very small numbers, you may find 'scaled numbers’ 
more. convenient to use. If you want to type numbers using 'binary' or 
'hexadecimal', you can do this too. See Part III for details. 

Text (strings) 

A text string (or just 'string') is a sequence of between 0 and 4096 text characters. 
(Note that a BASIC 2 line cannot exceed 255 characters.) When typed in a program, 
the string must start and end with double quotes (") - these are however not part 
of the string. 

There are 256 different text characters, each of which can be identified by a number 
in the range 0 to 255, known as its internal code (or, more commonly but less 
accurately, its ASCII code). The most familiar characters are those on a typewriter 
keyboard: numbers, letters and punctuation marks. For a full list of characters and 
their codes, see Appendix I. 

Typical text strings are: 

"" (a 'null string’) 

"and did those feet" 

"Catherine Louise, spinster of this parish" 

"23" 

Note that the last is only a string because it is enclosed in quotes; without the 
quotes it would, of course, be the number 23. 

You can type most characters directly using the keyboard, using single keys or 
combinations of keys, as described in your other guides. You can also create any of 
the 256 characters, using a BASIC 2 function (see CHR$). 





Getting information (input) 

Programs rarely invent the information they use - they usually have to obtain it from 
somewhere. There are four main sources: 

- inside the program 

- the user (for example, by typing) 

- disc files 

- the operating system 

The last three classes are usually referred to as 'input' (because information is 'put' 
'in' to the program). It is this ability of a program to use information supplied when 
it is run (rather than when it was typed) which makes programs so versatile. 

Once 'got', information is held in variables. These can store numbers or text, so all 
input to a program is converted into one of these two forms, regardless of where it 
originates. 

The types of information were described in the preceding section. This section 
described information sources, while the following section describes variables. 

Information from within the program 

If the information that a program uses is fixed, the simplest way to provide it is 
typing it into the program. This is done using constants, either in the instructions 
that use the information: 

PRINT "***SUB-TOTALS***" 

or by assigning the constant to a variable and then using that variable instead of the 
constant in subsequent instructions: 

titles = "***SUB-TOTALS***" 

PRINT titles 

A variable used in this way is sometimes called a 'pseudoconstant', because once it 
is given a value, you are using it as if it were a constant. 

You have already met both methods in the example programs and will rarely write a 
program that does not use them to some extent. Pseudoconstants have several 
advantages over constants: 

• if the constant is a long string or number, you'll only need to type it (and get it 
right!) once, and can then use the shorter and easier-to-remember variable name 
throughout the rest of the program 

• if you assign the pseudoconstants all in one place, you will find it easier to change 
the program. For example, if you use the variable clients to hold the client name, 
you can easily adapt the program for a different client or client name, by assigning 
the new name to clients, once, rather than changing each use of the name 
(constant) throughout the program 

• pseudoconstant names can be chosen to make the program easier to understand, 
thereby making it easier to check or change. For example, the numeric expression 
'cost*markup' explains itself, unlike 'cost *0.25' 
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If you use a lot of pseudoconstants in a program, you can set them up most 
conveniently by using the keywords DATA and READ. DATA is followed by a list of 
string or numeric values, separated by commas. READ is followed by a variable (or 
list of variables separated by commas), to which it assigns values from the list of 
DATA items. 

For example, if you wanted to store the number of days in each calendar month, you 
could use the following DATA statement: 

DATA 31,28,31,30,31,30,31,31,30,31,30,31 

Then use the following READ instructions to assign the information: 

READ jandays 
READ febdays 
READ mardays 

etc 

Or, to save typing, you could include several variables in the READ instruction: 

READ jandays,febdays,mardays 

(READ and DATA are particularly useful for assigning constants to a special type of 
variable called an array. This is described below.) 

You may have any number of DATA statements m a program. BASIC 2 treats them 
as if they were all in a single list of constants, starting with the first DATA 
statement in the program. Each time READ is used, it reads the next value from this 
list. If the program tries to READ more values than are in the list, an error is 
generated. 

Information from the user 

The facilities described so far allow you to write simple programs that perform 
calculations or print messages. They are very limited, though, because each time 
you run such programs it will produce exactly the same results: very commendable 
consistency, but rather inflexible! If you want one of these programs to do 
something even slightly different, you have to change it. then run it again. 

For example, say you operate a (very!) simple retail operation, selling a single 
product and want'a program to tell you how much to charge for it in order to make 
a (very modest) profit of 20%. The following program would do: 

cost = 10 
profit = 0.2 

PRINT "The price to charge is cost+cost*profit 

(Remember that the semicolon is used to separate items in a PRINT instruction.) 

Type this program in and run it. (Don’t forget to clear the current program with 
NEW first.) 

The program works well, but is rather limited: if the cost of your product changes, 
you must retype the first line; if the required profit changes, you must retype the 
second line. This is all very tedious and rather error-prone. (Try it now and see.) It 
also means that only somebody who knows how to modify the program can use it to 
calculate the price when conditions change like this. 



The real problem is with the first two lines, because they contain information that is 
constant, while you want the program to cater for information that varies. 
BASIC 2 provides a solution in the form of a command called INPUT, which asks for 
information when the program is run then assigns it to specified variables. 

To see it in action, change the first line to: 

INPUT cost 

When you run the program now. it displays a ' r and nothing else. It is waiting for 
you to type a number, followed by I *-> I . When you do so. it will assign the number 
to the variable ‘cost’ and carry on. Type a number now and press I «-■ I . Run the 
program again, typing a different number. 

The changed program is now: 

INPUT cost 

changed 

profit = 0.2 

PRINT "The price to charge is cost+cost*profit 

INPUT can also be used to input text to a string variable, by simply using a string 
variable in the instruction (such as INPUT persons). There are certain restrictions on 
what can be typed in response to INPUT'S prompt. In particular, you cannot type a 
comma. In Part III we show how the LINE INPUT statement can be used to 
overcome these restrictions. 

The type of variable used with INPUT determines how the text you type will be 
treated. If it is a numeric variable, your reply must be numeric; if it is a string, your 
reply will be taken as a string - even if it is a number! If you type something that is 
not a valid number when input is to a numeric variable, you will be asked to type it 
again. 



INPUT has successfully made your program a bit more versatile, but in its new form, 
the program is still a little daunting to use. When someone runs the program, will 
they know what to do when the '?’ prompt is displayed? The program should give 
them a clue! You have already met a command that can be used here: PRINT, with 
a string. 

Add an extra line to the program to display a message (prompt) telling the user 
what to do when they see the '?'. Try the modified program and see if this helps. 

Here is one solution: 

PRINT "Type item cost as pounds.pence, then press RETURN" 

v v ■■ * 

prompt (text string) 

INPUT cost 
profit = 0.2 

PRINT "The price to charge is "; cost+cost*profit 
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Did you remember to put the new line at the start of the program 9 

The wording that you use in a prompt is totally ignored by BASIC 2. but is VERY 
important to the people who will use the program. Choose the wording carefully, 
using words and concepts that users will understand and they will find the program 
much easier to use. 


Because INPUT often needs a prompt to explain to users what they should type, you 
can include a prompt in the INPUT mstrucuon. Usmg this, you can combine the first 

two lines, as follows: 


INPUT "Type item cost as pounds.pence, then press RETURN 
v--- sr - 

prompt 


it 

S 


cost 


variable 


profit = 0.2 

PRINT "The price to charge is "; cost+cost*profit 

Note that a prompt used in an INPUT instruction must be a string constant, not a 
string variable. (Can you think why? If it were a variable. INPUT would try to assign 
a value to it, not display it as a prompt!) The prompt must also come before the 
variable, not after it. We’ll see how to extend this in Part III. 

Note the comma after the text string. This stops BASIC 2 displaying the *?’ prompt 
after your text prompt. If you want the ’?’ displayed, use a semicolon instead of the 
comma. 

Now modify the program to prompt for a profit value too. Run it and check that it 
works correctly. 

BASIC 2 provides another method of getting information typed by the user, in the 
form of the function INKEYS. INKEYS checks to see if any key has been pressed 
since the last keyboard input and either returns it as a single character string, or 
returns a null string if no key has been pressed. An instruction usmg INKEYS takes 
the form: 

variables = INKEYS 

Since INKEYS does not wait for the user to press I <-» I (or any other key), it is used 
quite differently to INPUT. It has two main uses: to check on what the user has 
typed while carrying on with some lengthy task, and to provide a quick and easy 
way to input single characters (with no need to press l ^ l ) 

Unfortunately, both uses require BASIC 2 keywords that you have not met yet. To 
see INKEYS (and the related INKEY) in action, you will have to wait for the next 
chapter! 

The other main way that a user can supply information to a program is by 
manipulating the mouse. This is described in Part III. 

Information from a disc 

The third source of information is from ‘data files’ stored on discs. Data files can be 
created using BASIC 2, to hold numeric and string information, rather like variables 
or DATA statements. However, unlike variables, the information in a file is preserved 
until you deliberately change it: it is not lost when you do things like running a 
program or switching the computer off. 

Data files are described in detail in Parts III and IV. 










Information from the operating system 

A fourth, but rather minor source of information is the computer’s operating system. 
Keywords in this group provide two main types of information: 

- about discs and files 

- about other components (clock and output devices) 

An example of the first type is the command FILES, which displays the names of 
files on a disc. Try it now: 

Type: FILES|“ED 

An example of the second is the function TIME, which produces a numeric value 
indicating the time (in hundredths of a second since midnight), read from the 
computer’s real-time clock. Try it now: 

Type: PRINT TIME/100; "secs since midnight" ! <-* I 

Exercises: input 

1 Which of the following is not a valid number? (HINT: try each in a PRINT command) 
a -1 

b 123,456.789 
c 123.0123 
d 123.0123 

2 What is wrong with the following program? Correct it and run it to check the result. 
(HINT: a subtle error. Remember that a program should do what it says) 

INPUT "How many oranges";oranges 
INPUT "How much each (in pence)";cost 
total = oranges*cost 
PRINT "Your oranges will cost £"; total 

Solutions 

1 The following are not valid: 
b - numbers must not include commas! 

c - the character after the decimal point is the letter 0, not the digit zero. 

2 The last line displays a pound sign before the calculated total, but the calculation is 
in pence! Change it to: 

PRINT "Your oranges will cost (pence)";total 

or 

PRINT "Your oranges will cost £";total/100 
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Information storage (variables) 

No matter where its information comes from, a program must store the information 
it is working with, in variables. A variable is simply a name for the item of 
information, which the program will use to refer to it. (BASIC 2 uses the variable 
name to identify the area of memory it has set aside to store the information and to 
decide how to handle it.) You might like to think of a variable as a drawer with a 
name on it, ready to hold information. 

Choosing variable names 

BASIC 2 leaves the choice of variable name largely up to the programmer. The 
shortest variable name is 1 character, the longest is 40 characters. The name must 
not be exactly the same as a keyword (remember that capitals and small letters are 
treated as equivalent), but may include a keyword. (For a list of keywords, see the 
appendices.) 

The name may include any of the following characters from the GEM character set 
(see Appendix I): 

• any of the letters A to Z or a to z (the capital and small letters are considered 
equivalent) 

• any of the accented letters and greek letters (see Appendix I). These may however 
cause problems when using certain printers to list programs. 

• the underline character _ 

• numbers 0 to 9 in any position other than the first character 

• X ! # or $, but only as the last character. $ denotes a suing variable. The others 
denote a numeric variable, for compatibility with earlier versions of BASIC 

• ( and ) or C and 1 but only in array variables - see below 

• { and > but only in substrings (see Part m) 

• . but only in record fields (see Part IE) 

Thus, the following are valid variable names: 

a 

stopper 

sane-mind_and_body 

NaneS 

partBex 

The following are not: 

0a 

- starts with a numeral 

stop 

- identical to the keyword STOP 

get#lost 

- # used other than at the end of a name 





first nameS 

- includes a space 

Remember that capital and small letters are considered equivalent in variable 
naming, so that the variable nameS is the same as NameS, NAMeS, etc. 

Within these limitations, you should choose variable names that indicate their 
purpose. For instance, for a variable used to maintain a trial balance, use 'balance' 
or even ’trial-balance’, but not something completely obscure, like *zz\ Meaningful 
names make your programs easier to write, change and understand. 

On the other hand, try to keep variable names reasonably short, to save typing and 
memory and reduce the number of typing errors you.will make! Try typing: 

trial-balance-carried-forward = trial-balance-carried-forward + 1 

a few times and I think you’ll agree. 

The short life of a variable 

Variables are by their very nature rather flighty, transient things. The current value 
of a variable is lost whenever you: 

- run a program 

- load a program 

- leave BASIC 2 

If you try to use a variable for which the value has been lost, its value will be 0 (for 
a numeric variable) or the null string "" (for a string variable). (But see OPTION 
TRAP.) 

There are several ways to preserve the information contained in variables so that 
you can use it later, but for now just remember when writing a program to assign 
values to variables before using them; don’t assume they will be preserved from the 
last time you used a program: THEY WON'T. 

Numeric variables 

The type of a variable is indicated by the last character of its name. If it is a $, the 
vanable is a string variable, otherwise it is a numeric variable. 

The range and precision of numbers that you can store in a numeric variable are 
exactly as described previously, for typing numbers. 

(BASIC 2 also has a concept of ’storage class', which applies to arrays and records, 
to help reduce memory usage. See Part HI.) 

String variables 

String variables are distinguished from numeric variables by having a suffix of $. The 
maximum number of characters that can be stored in a string variable is 4096; the 
minimum is zero (the null string, ’”'). Characters with codes anywhere between 0 
and 255 can be stored in strings. For a full list of characters and codes, see 
Appendix I. 

Organising variables (arrays) 

The variables described up until now have all had quite independent existences. 

While this is entirely satisfactory for programs that simply take single items of_ 
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information, manipulate them and print the results, there are times when you would 
like to hold lists or tables of information in variables, preserving the relationship 
between them. 

One way of doing this is to use related variable names. For example, to store the 
names of record albums, you could use the string variables 'albumlS', 'album2$'. 
'album3$' etc. 

While this method of naming makes the relationship obvious to you or I, BASIC 2 
entirely misses the point - it sees no particular ordering or grouping in these names, 
so you cannot take advantage of it in your programs. For instance, to print the name 
of album 2. you would need the instruction: 

PRINT album2$ 

To print the name of album 3, you need a different instruction: 

PRINT album3S 

And so on, for each name. Even more seriously, there is no way (with the 
commands described so far in this guide) to construct a program to perform simple, 
useful tasks like printing the name of the album corresponding to a number. 

BASIC 2 provides a solution to these kinds of problems by allowing you to use 
variables which are organised into structures like lists or tables. These are called 
'arrays’. The variables in an array are called (naturally enough) 'array variables' or 
'array elements’. 

All the variables in an array have the same basic name and type, but are 
distinguished by their 'array index', which is their position in the array. This is a 
numeric value (or values), in brackets after the anay name. 

The simplest form of anay is a single dimensional anay, which you can think of as a 
list, with each anay variable's index conesponding to its position in the list, for 
example: 

PRINT albumS(3) 

score (pupil) = score(pupil) + history 

Anays should usually be set up before use, using the keyword DIM ('DIMension'). 
This is followed by the name of the anay and the range of each of its dimensions, in 
brackets. 

For example, to set up an anay named album!: 

DIM album$(3) 
v -> r ' v v' 

j range 
array name 

Defined in this way, the elements start at number 0 and stretch to the range, so 
albums is an anay of four string variables: 

albun$(0) 
albunS(l) 
alburf (2) 
albu«$(3) 

Anay variables can be used exactly as the equivalent (non-array) variable, but they 
are mainly used as indicated above: for storing or processing lists or tables of 



information. For example, to solve the problem posed above, the following program 
will suffice: 

DIM album$(3) 

album$(1)="Dark side of the moon' 1 
album$(2)="Vivaldi's four seasons" 
album$(3)="Bridge over troubled water" 

INPUT "What number album do you want a title for (1-3)";number 
PRINT albumS(number) 

The first line defines the array. The next three give values to elements 1 to 3. The 
next line gets the number of the album wanted by the user. The final line prints its 
title, by pnnting the corresponding array variable. 

Note that you need not define all variables in an array: in this case. album$(0) has 
been totally ignored. 

If an array has not already been set up using DIM, when it is first referred to, it will 
be set up with the right number of dimensions, each with 11 elements (numbered 0 
to 10). If this is acceptable, you won’t need to define the array with DIM, but this is 
a bad habit to get into, as it tends to waste memory and make the program more 
difficult to read. 

Arrays can have many dimensions, not just the single one of album$() above. For 
instance, if you wanted to record the temperature at a number of points within a 
room, you might use ’temp(x,y,z)’ where x, y and z are the co-ordinates of the 
points within the room. If you wanted to record how this information changed with 
time, you could use ’temp(x,y,z,t)’, where t is the time scale, and so on. The array 
could be dimensioned using, for example, DIM temp(10,10,6,15). 

(You can also define arrays so that they start at an element other than 0 and save 
memory, by restricting the range of values they can hold. See Part III for details.) 

Note that in general, you cannot use an entire array as a variable, just use the 
individual elements in it. An array is just a way of organising variables for your 
convenience. 

The quickest and easiest way of setting up an array from constants is to use the 
keywords DATA and READ, introduced previously, and a control structure called a 
‘loop’. Contrast the following program fragments, which both store the days in the 
month in an array called ‘days’. The first uses DATA, READ and a structure called a 
'FOR loop’ to produce code which is compact and easy to understand; the second 
does not. The FOR loop may be used to carry out a sequence of operations a 
specified number of times. The start of the sequence is signalled by the FOR 
statement and the end by the NEXT statement. The variable which follows FOR (ie. 
month below) is incremented each time round the loop. The values following the 
equals sign give the limits between which the variable is incremented (ie. 1 to 12 
below). You will find the FOR loop is used extensively in BASIC programming. (The 
’FOR loop’ will be described in detail later.) 
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DIN days(12) 

DATA 31,28,31,30,31,30,31,31,30,31,30,31 
FOR month = 1 TO 12 
READ days(month) 

NEXT month 

DIN days(12) 
days(1) = 31 
days(2) = 28 
days(3) = 31 
days(4) = 30 
days(5) = 31 
days(6) = 30 
days (7) = 31 
days(8) = 31 
days(9) = 30 
days(10) = 31 
days(11) = 30 
days(12) = 31 

(You can also organise variables by using ‘record fields’, packing numeric and string 
values into strings then extracting them again. These are mainly used with data 
files. See RECORD.) 

Choosing variable types 

There are two main types of variable: numeric and string. 

If you need to store text, you must use a string variable - you cannot use a numeric 
variable for this. 

If you need to store a number for use in calculations, you must use a numeric 
variable - you cannot use a string variable for this. 

If you need to store a number that won't be used for calculations, you can use either 
a numeric or a string variable. 

Array variables are generally useful when the information being stored is obviously 
ordered, into lists (1 dimension), tables (2 dimensions) or structures with more 
dimensions. Using an array lets you preserve that ordering. 

A typical example of a table of data is an address list, which could be stored using 
separate arrays for the name, address and telephone number, linking them for each 
individual by a shared index number (eg name$(22) plus address$(22) plus phone(22) 
is the entry for one individual). 

(Another way to store linked information is to use string arrays and records: see 
RECORD.) 




Exercises: variables 

1 Write a program that asks the user to type a number in the range 0-9, then 
displays the corresponding word (zero, one, two, three etc). (HINT: use an array for 
the words) 

2 Which of the following variables is most suitable for storing numbers for arithmetic? 
(HINT: variable name, type and organisation!) 

count 

counts 

count,up 

width 

print 

a 

a# 

a$ 


Solutions 


1 DIM number$(9) 

DATA zero,one,two,three,four,five,six,seven,eight,nine 
FOR a = 0 TO 9 
READ numbers(a) 

NEXT 

INPUT "Number in range 0-9";number 
PRINT numbers(number) 


2 count 
counts 
count-up 
width 
print 
a 

a# 

a$ 


yes 

no - string variable, so cannot be used to store numbers for arithmetic 

no - not a variable name, as 7 used 

yes 

no - illegal name: PRINT is a keyword 
yes, but not very informative 
yes, but not very informative 
no - string variable 
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5. MANIPULATING INFORMATION (PROCESSING) 


This chapter describes the facilities used to manipulate numeric and string 
information, and illustrates ways in which they can be used. Many of the concepts 
used here have already been presented in the previous chapter. 

Programs all deal primarily in information. As described previously, this comes from 
somewhere (input) and goes somewhere (output). The very simplest programs do 
very little else; like some high-tech funnel, they simply transport information from 
one place (eg keyboard) to another (eg screen or printer). However, most programs 
do rather more than transport information; they use rules, embedded in the program, 
to transform the received information into related but different information, which is 
then output. 

For example: 

- adding together the details of separate bills to produce an analysis such as total 
expenditure and current balance 

- averaging the marks from individuals in a class to produce the average, lowest 
and highest marks for the class 

- re-organising a list of names into alphabetical order, eg a phone directory 

- producing a list of co-ordinates defining the shape of a picture from input 
provided by operation of the mouse 

These rules governing the transformation of information are mainly produced 
through the use of functions and operators, in expressions. 

Functions, operators and expressions 

Information is manipulated mainly using the types of keywords and symbols 
described in this section. The resulting information is either output immediately by 
using it with an output command, or stored in a variable, for use later. 

The simplest way to manipulate information is by using keywords called 'functions'. 
A function is followed by brackets, containing one or more items of information 
(called its argument(s)). When a function is evaluated, its argument(s) are used to 
produce a single result. 

There are functions to calculate, for example, the square root of a number, the 
lowest of a list of arguments or the number of characters in a string. 

There are two main classes of function, depending on the type of result they 
produce. 'Numeric functions' produce numeric results, while 'string functions' 
produce string results. You can tell which type a function is by the last character of 
its name: if this is $. the result and hence type are string, otherwise the result and 
type are numeric. 

BASIC 2 functions provide 'ready made' solutions to many calculations, which can 
be combined to solve common problems with just a little help from other parts of 
the language. 
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BASIC 2 also provides a more open-ended way of manipulating information, through 
the use of 'expressions'. 

An expression allows you to combine information and/or functions using symbols 
called 'operators', to solve a very much wider range of problems. The most familiar 
operators are the ‘arithmetic operators': plus (+), minus (-), multiply (*) and divide 
(/)• 

An expression consists of a sequence of information items/functions, strictly 
alternating with operators: 

information operator information 
or 

information operator information operator information 
etc 

For example, using the arithmetic operators: 

2 + 3 

stored + bought — used 
Or the string operator '+': 

"Mr. " + firstnameS + lastnameS 

All the items in an expression must be of the same type (string or numeric). 

Like a function, an expression produces a single result, which is either numeric or 
string. 

As mentioned above, information items can also be functions, for example, using the 
square root function SQR: 

SQR(areal) + SQR(area2) — subtotal 

Finally, a function's arguments can also be expressions. The expression is evaluated 
to produce a result, which is then used as the function's argument. For example: 

SQR<a*a+b*b) 

Manipulating numeric information 

The main numeric operators, for addition, subtraction, multiplication and division, 
have already been described. There are several other numeric operators, but these 
will not be described here (see Part m). 

The only numeric function you have met so far is SQR, for determining the square 
root of its argument. 

Numeric functions fall into three main groups: 

- 'scientific' functions, such as found on powerful calculators (for trigonometry, 
logarithms and exponentiation) 

- simple statistical functions 

- conversion functions 




A simple scientific function is the trigonometric function SIN, which produces the 
'sine' of its argument. For example: 

PRINT SIN(0.5> 

Sines are useful for calculating angles and dimensions of triangles. For example, if 
you know your ladder's length and safe working angle, you can use SIN to calculate 
how high it can reach up a vertical wall. 

SIN's argument is an angle, which will normally be in radians. To switch between 
using radians and degrees, use the Program menu option 'Angles in’ or the 
commands OPTION DEGREES and OPTION RADIANS. 



90 degrees 
n/2 radians 


180 degrees 
k radians 



0 degrees 
0 radians 

270 degrees 
3n/2 radians 


To solve the above problem, you could use the following: 

OPTION DEGREES 
ladder = 10 
angle = 80 

PRINT "Height of wall in metres = ";ladder*SIN(angle) 

There are also conversion functions called RAD and DEG, which convert their 
arguments to radians and degrees, respectively, so the program could instead be 
written as: 

ladder = 10 
angle = RAD(80) 

PRINT "Height of wall in metres = ";ladder*SIN(angle) 

Another simple conversion function is FLOOR, which converts its single argument 
into an integer ie a number without a fractional part. For example, try: 

Type: PRINT FL00R(5.9) n=n 

5 

For a positive argument, FLOOR simply removes the fractional part; for a negative 
argument, it produces an integer which is the next most negative integer: 

Type: PRINT FL00R(-5.9) n=H 

-6 

FLOOR is of course normally used to convert the value of an expression or variable 
to an integer - there’s not much call for converting constants! 








ASC is another conversion function, that converts the first character of its string 
argument to the corresponding character code (see CHR$, below): 

INPUT "Type a letter, then RETURN";letters 
PRINT "Its character code is ";ASC(letters) 

A statistical function is MAX, which produces the value of the highest (most 
positive) of its arguments. For example: 

highest.score = MAX(score1,score2,score3) 

MIN is similar, producing the value of its lowest argument. MAX and MIN are 
somewhat unusual in allowing you to use a variable number of arguments. Most 
functions allow only a fixed number. 

Manipulating string information 

The only operator that will work with strings is +, which adds the second string 
onto the end of the first (or a third string onto a second, etc). There are however a 
number of string functions. 

These provide three main types of facility, allowing you to build, dissect or convert 
strings. 

The function STRINGS creates a string by repeating a single character, up to 4096 
times. The first argument specifies the length of the string, the second gives the 
character to build it from. For example, to print a string of 30 hyphens: 

PRINT STRING$<30,"—") 

Note that the two arguments must be in the order specified. This is true for most 
functions that have multiple arguments. 

You may specify the character either as a string (like “-") or as its code. For 
example, to assign 14 alpha characters (character code 224) to the variable greek$: 

greekS = STRINGS(14,224) 

A simple method of processing parts of a string is provided through using 
‘substrings'. The part of the string required is specified by a range, enclosed in the 
brackets "C" and 

string {.range"} 

string can be any string constant, variable or expression. Characters in it are 
numbered from the lefthand end, the first character being numbered 1. 

range is one of the following: 

Cm TO n> - the mth to the nth characters, inclusive 
Cm TOJ - from the mth character to the end of the string 
•CTO n> - from the first character to the nth. inclusive 
{m} - the mth character only 

If m or n are negative, they are taken as the mth or nth from the righthand end of 
the string, so that, for example, <-l> returns the last character. 

By using substrings you can extract part of a string, for example: 

PRINT name$C1 TO first-len> 



You can also use substrings to change part of a string, for example: 
nameS-CTO 4> = "Anne" 

Strings can also be pulled apart using string functions. These have mainly been 
retained for compatibility with earlier versions of BASIC, since substrings provide a 
neater and more consistent method to the same end. These functions allow you to 
pick out characters from the start (LEFTS), middle (MIDS) or end (RIGHTS) of a 
string. 

For example, LEFTS uses two arguments: the first is the string (constant/variable/ 
expression) to dissect, and the second is the number of characters to return from its 
start. For example, to assign the first three characters of the variable 'nameS' to 
'titles': 

titles = LEFT$(name$,3) 

An example of a conversion function is UPPERS, which produces a version of its 
argument in which all lower case (small) letters have been converted to the 
equivalent upper case (capital) letters. Try it now: 

Type PRINT UPPER$("1234567890abcdefqHIJKL") n : n 

UPPERS also converts accented characters - to the corresponding accented capital 
(or unaccented capital if there isn't an accented one). 

(Conversion from capitals to small letters is performed similarly, using LOWERS.) 

Another highly useful conversion function is CHRS, which converts its single 
numeric argument into the corresponding character ie it converts an character code 
to a character. This is the inverse function to that of ASC. As described previously, 
character codes are integers in the range 0 to 255. To see CHRS and ASC in action, 
type in and run the following program: 

INPUT "Type a single character, then press RETURN";letters 
code = ASC(letterS) 

PRINT "The character code for letterS;" is";code 
PRINT "The character for";code;" is ";CHR$(code) 

PRINT "The next character after it is ";CHR$(code+1) 




Exercises: information manipulation 

1 You have now met and seen used the following keywords, used to process numeric 
and string information. Classify each as a string/numeric operator/function: 

Operator Function String Numeric 

+ 

* 

/ 

ASC 

CHRS 

FLOOR 

LEFTS 

MAX 

RAD 

SIN 

SQR 

STRINGS 

UPPERS 

2 Write a program to request the dimensions of a rectangular field, then calculate and 
display its area (area of a rectangle = length of 1 side multiplied by the length of an 
adjacent side). 

3 Write a program to request the scores (in the range 1 - 20) of three individuals, 
then display them as horizontal bars, in the same order as typed. (HINT: STRINGS 
repeats a character n times) 

4 Write a program to print the entire 'normal' character set ie the characters 
corresponding to character codes 32 to 255. (HINT: CHRS converts character codes 
to characters; FOR...NEXT provides a quick way to repeat instructions) 

5 Write a program to request a string from the user, then print the first character, then 
the first two characters, then the first three characters, until the complete string has 
been printed. (HINT: LEN tells you the length of a string. Substrings can be 
extracted from a string using O. A FOR loop provides easy repetition.) 



Solutions 


i 


+ 


* 

/ 

ASC 

CHR$ 

FLOOR 

LEFTS 

MAX 

RAD 

SIN 

SQR 

STRINGS 

UPPERS 


Operator 

Function 

String 

Numeric 

✓ 


/ 

/ 

/ 



/ 

/ 



/ 

/ 



/ 


/ 


/ 


/ 

/ 



/ 


/ 


/ 

/ 



/ 


✓ 


/ 


/ 


/ 


/ 


/ 


/ 


/ 

/ 



/ 




2 INPUT "Length of first side of rectangle (metres)" 
INPUT "Length of adjacent side (metres)";side2 
area = side1*side2 

PRINT "Area of field is";area;" square metres" 


3 DIM score(3) 

FOR count = 1 TO 3 

INPUT "Player's scored — 20)";score(count) 
NEXT 
PRINT 

FOR count = 1 TO 3 
PRINT STRING$(score(count),"*") 

NEXT 


(Note how score(O) is not used, to simplify processing.) 

4 FOR code = 32 TO 255 

character* = characters + CHRS(code) 

NEXT 

PRINT characters 

5 INPUT "Type the text to display",textS 
FOR length = 1 TO LEN(textS) 

PRINT textSCTO length> 

NEXT 


;side1 








6. OUTPUT 


Output is the eventual goal of any computer program. It doesn’t matter how clever a 
program is, if the results are not output, the outside world will never get to hear of 
what it’s been doing and all its efforts will have been in vain. 

The three main routes for output that you can use with BASIC 2 on a typical 
computer system are: 

- text or graphics, to the screen (messages, prompts, totals, doodles, a pie chart) 

- text or graphics, to a printer (a letter, price list, line graph) 

- numeric or string information, to a disc file (a phone list, database, copy of a 
letter) 

Text output consists of characters from the GEM character set, usually (but not 
necessarily!) combined to produce sensible, legible text such as English sentences 
or tables of figures. 

Graphics output consists of straight lines, points, arcs, shaded areas etc. usually 
combined to produce pictures (such as a pie chart, self portrait or engineering 
drawing) rather than text. 

Output to the screen is the fastest method of achieving visible results and doesn’t 
require any extra equipment or use up any materials. Screen output can be visually 
exciting and highly informative, but has some disadvantages. For example, it is 
limited in size, so you may not be able to display all the information that you want 
(but see ‘Windows’, below) and can only be viewed while the program is running, 
so the information is not very portable. 

Output to a printer (or plotter) is rather slower and requires additional equipment 
and uses up materials (paper and ink). However, printed output has the major 
advantage of being permanent and portable, so it can be used away from the 
computer, or while a different program is running. 

Output to disc files is not really for human consumption, but destined for later use 
(input) by computer programs. Thus it performs a rather different role to screen or 
printer output, mainly serving to save users having to re-enter information. 


Streams 


The commands used to output text and graphics are generally the same, regardless 
of what device (screen, printer, plotter etc) they are sent to. The device used will 
usually be the screen, unless you specify another device, by including its 'stream' in 
the output command. 

A 'stream' is simply # followed by the stream number. There are 16 streams 
allowed (0 to 15). BASIC 2 sets up 0 for printer output and 1 and 2 for the screen, 
but you can (re)define the device attached to any stream, using the command 
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Using OPEN, you can easily change the devices used for output. This has a number 
of uses. For example, while developing a printing program, you might choose to 
send 'printed' output to the screen initially, to save printer paper! 

OPEN also defines the capabilities of the device ie whether the device is a screen, 
printer, disc file. etc. Different output devices have different capabilities, so that 
some commands may not work (or may work differently) for certain devices. As far 
as is practical, commands that cannot be obeyed by an output device will simply be 
ignored by it. 

The screen can show text and graphics. As you will see below, it is divided into 
separate areas known as windows, which can display text only, or text and graphics 
(see SCREEN). 

The remainder of this chapter describes text and graphics output to the screen, 
initially ignoring the subject of windows. Output to printer and discs is described in 
Part m, but has much in common with screen output. 

Simple text output 

Text output to the screen can consist of any of the GEM text characters (codes 
0 - 255). You will probably mainly use characters with codes in the range 
32 - 127, as these include all the (unaccented) letters, numbers, punctuation marks 
and common symbols. See Appendix I for full details. 

This section summarises the information you have already learned about printing 
text on the screen and extends it somewhat to cover two main extra points: 
formatting output and controlling the screen. 

There are many other facilities available which will not be described further in this 
chapter, in particular the ability to print text in a number of different sizes and styles 
(such as underlined and bold) and at angles. (See Part III.) 

Using PRINT 

The command used to display text on the screen is PRINT, which has been used 
extensively in previous examples. This displays items as text, regardless of whether 
they are string or numeric, constants, variables or expressions. PRINT automatically 
converts numeric information to the equivalent string before printing it, so the 
division of information types into numeric and string becomes largely irrelevant 
when used for text output. 

Text is usually displayed starting at the position of the 'cursor'. This may be 
displayed on the screen as a rectangular blob (or thin vertical line), or not be 
displayed at all, depending on previous commands (see CURSOR). It behaves rather 
like the print head on a golf ball typewriter - moving across and down the screen 
('paper') to indicate where the next character will be displayed ('printed'). Note that 
the cursor is quite distinct from the pointer which you move with the mouse. 

To make the cursor visible, we must give a special command 

Type: WINDOW CURSOR ON 

Note how the cursor appears as a cross. 

A PRINT instruction always starts with the keyword PRINT, which may be followed 
by items to print and items to control that printing, known as 'print functions'. 


•4 



The simplest PRINT instruction consists of just the keyword PRINT. This moves the 
cursor to the start of the next line and is most frequently used for producing blank 
lines. 

Next simplest to understand is PRINT followed by a single item of information. For 
example: 

Type: PRINT 2+2 \J±J 

Note how the cursor moves to the start of the next line after displaying '4‘. To stop 
it doing this, you can follow the print item with a semicolon (;) or a comma. A 
semicolon makes the cursor stay at the end of the item it has just printed - to see 
the difference it makes, type and run the following: 

PRINT "Text on" 

PRINT "two lines" 

PRINT "Text on 
PRINT "one line" 

Note how the information from the first two lines is displayed on separate lines, 
while the information on the last two lines is displayed together on a single line, 
courtesy of the semicolon at the end of the third line. 

A comma causes the next item to be displayed a little to the right of the end of the 
first. For example: 

PRINT "Text separated by", 

PRINT "a comma" 

Using the comma, you can produce neat tables quite easily. 

There is no need to use a separate PRINT instruction for each item to display - you 
can display several items using a single instruction, by putting a separator between 
each item, which can be a comma or a semicolon. For example: 

PRINT "2 times 2 is";2*2 

Commas and semicolons in a list of items have the same effect on positioning of 
items as described above ie the semicolon makes the item appear immediately after 
the previous item; the comma produces a small gap. 

However, before displaying each item, BASIC 2 always checks that it will fit onto 
the remainder of the line. If not, it will display it on the next line, regardless of 
commas or semicolons. 

Note that items to be printed must be separated using separators; spaces are not 
enough. 

Formatting output 

PRINT has been used widely in example programs and instructions above. You may 
have noticed that the results produced using it have often been rather untidy, being 
split over several lines where they would look better on one. not lining up vertically, 
etc. 

Using semicolons and commas to modify printing helps a lot. but BASIC 2 provides 
you with other facilities specifically designed to give you control over two aspects of 
the format of displayed items: their position on the screen and the fonn they take 


65 


OUTPUT 





As described above, commas can be used to control positioning, producing 
tabulation. An item printed after a comma is printed in the next available 'print 
zone’ to the right of the previous item (if there is room on the line). Print zones are 
positions usually every 18 character positions across the screen, rather like tab stops 
on a typewriter. Type and run the following program to see them on the screen: 

PRINT "Print zone numbers" 

PRINT "1","2" / "3" / "4"/ , 5","6" 

(You can change the position of the print zones to every n characters across the 
screen, using the command SET ZONE n.) 

A similar, but more flexible method of providing tabulation is to use the print 
functions TAB(co/) and AT(c ol.line). TAB moves the cursor right to column co! on 
the current line, or to column col on the next line if the cursor is already to the right 
of that position. AT moves the cursor to the specified position on the screen. Both 
are printed as if followed by a semicolon. 

(Columns and lines are numbered starting from the top left corner of the 'virtual 
screen', which is column 1. line 1. Note that this starting point may not be the same 
as the top left comer of the window. See Part El for details.) 

The format of individual items can be controlled using the keyword USING. USING 
is followed by a 'format template' which specifies how to display subsequent items 
in the print instruction. Full details of USING and templates are given in Part HI, but 
the following example should give you an idea of the flexibility it provides. 

If you are displaying amounts of money, you will often want to tabulate them neatly. 
At first glance you might think that TAB is all you need. For example: 

sum(1) = 1.24 

sum(2) = 0.333 

sum(3) = 14444.1 

PRINT "Sum = ";TAB(20) sum<1) 

PRINT "Sum = ";TAB(20) sum<2) 

PRINT "Sum = ";TAB(20) sum(3) 

Type the program shown and run it. While the output is tabulated, the figures are 
aligned by their first digit, rather than by the decimal point, as is usual. 

The solution is to use the output formatting facility provided by USING and a 
'template'. Change the print instructions as follows and run the program again. 

PRINT "Sum = ";TAB(20) USING "###,###.##";sum<1) 

6tC ^ 1 ■ 1 ■ * 

template 

The ###,###.## part of the template specifies that the following item should be 
displayed as six figures to the left of the decimal point, followed by two to the right. 
The , part specifies that the figures to the left of the decimal should be placed into 
groups of three, separated by commas. (Specifying the printed format as two 
decimal places also forces rounding at the second decimal place, so that for example 
‘1.666’ would be displayed as '1.67'.) 



Controlling the screen 

Text output can include special characters (control codes) and sequences of 
characters (escape sequences) which are not displayed, but produce various other 
effects on the screen. A full list of these is given in Appendix I, but the following 
should illustrate the ways they are used and the types of results that can be 
obtained. 

Control codes are single characters with codes in the range 0 to 31 and 127. The 
main control codes obeyed are: 

Code Description 

7 BELL: sound a short bleep 

8 BACKSPACE: move text cursor left one column 

10 LINEFEED: move text cursor down one line, scrolling if necessary 

13 CARRIAGE RETURN, move cursor to start of current line 

27 ESCAPE: starts an 'escape sequence' 

127 DEL: delete character to left of cursor 


Example: 

PRINT CHR$(7);CHR$(7>;"WRONG! Try again" 

Escape sequences are fixed-length sequences of characters beginning with the 
ESCAPE character, (character code 27). There are more than 30 escape sequences, 
for example: 


Sequence 

ESC A 
ESC J 
ESC p 
ESC q 


Description 

move cursor up one line unless on top line (no scrolling) 
clear from current cursor position to end of window (virtual screen) 
print text as 'white on black' (reverse video) 
revert to normal video ('black on white') 


Example: 

PRINT "You are now ";CHR$<27);"p";"OVERDRAWN ,, ;CHR$(27);"q ,, 

(It may be of interest that the control codes and escape sequences obeyed by the 
screen are very similar to those obeyed by a computing industry 'standard' terminal, 
the VT52.) 


Virtual screens and windows 


All output to the screen is seen in 'windows'; separate rectangular areas that GEM 
allows you to move around the screen, re-size, scroll etc, using your mouse 
Windows make your single screen behave rather like a number of smaller, separate 
screens. 


There are two types of window: 'text windows' and 'graphics windows'. Text 
windows can be used only for text output, while graphics windows allow qraDhics 
output and a slightly different type of text output. (The description of text oE 
given so far applies equally to both.) Xl oul P ut 
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BASIC 2 allows you to use four windows, numbered 1 to 4. These are normally 
referred to in commands by using the number of the stream attached to them. For 
windows 1 and 2, this is initially set to the window number: 


Window Window Stream Use 

number name number 


1 Results-1 1 usual output window (graphics) 

2 Results-2 2 text window for output 

3 Edit 

4 Dialogue 



Output to a window is actually treated as being written to a larger area, know-’ as a 
'virtual screen'. Only that part of the output which lies within the screen window is 
displayed. 

This means that, for example, if text were printed in a window which is narrower 
than its virtual screen, you would only see part of each line. 

A window is defined as text or graphics by its virtual screen, which can be 
(re)defined using the SCREEN command. SCREEN also sets the virtual screen's size 
and behaviour of the window (see Part ID). 

Windows can be repositioned or resized with the mouse to suit what you're doing. 
For example, if you were typing or editing a program, you might choose to enlarge 
the Edit window, to get more room for typing and examining the program. 

You can also use the mouse to scroll a window, to examine previous output which 
had scrolled off the top of the screen. 

Windows can also be manipulated using BASIC 2 commands, for example, to 
re-size, move, scroll or clear a window or move the text cursor. (Once again, refer to 
Part IE for full details.) 

For example, to clear a window, use the command CLS (CLear Screen). This may be 
used on its own, in which case it will clear the window being used for output, 
usually the Results-1 window: 

CLS 

To clear a specific window, specify its stream in the CLS instruction. For example, 
to clear the Results-2 window (Stream 2): 

CLS #2 

You can also direct output to a specific window by specifying the window's stream 
in the output instruction, followed by a comma. For example, to PRINT to the 
Results-2 window (Stream 2): 

PRINT #2/ "a different view on the world" 

Note that you won't see this in the initial layout of windows as Results-2 is hidden. 
Use the mouse to move the Dialogue window to show Results-2. 


Graphics output 

Graphics output consists of dots, straight lines, arcs, patterns etc. As described 
above, it can only be displayed in a graphics window. 












BASIC 2 provides facilities to draw: 

- points and other markers 

- straight lines 

- rectangles 

- polygons 

- circles 

- pie segments 

- ellipses 

These can be drawn in a variety of colours (or intensities, on a monochrome 
monitor), line styles and line widths. Figures (such as circles or polygons) can be 
outline or solid and can be filled with a variety of patterns. 

To see the line types, widths and colours available, select the Lines and Colours 
menus with your mouse, or see Appendix III. 

You can also print text in a graphics window, which gives you extra facilities such 
as the ability to vary the text style and angle. (See Part III for details.) 

Graphics windows, units and positions 

The default output window is already set up for graphics, so you do not need to set 
up a graphics screen. 

Graphics are drawn on the screen by changing the colour of the individual dots that 
comprise it. There are thousands of these dots, called 'pixels' (picture elements), all 
over the screen: 



Graphics commands do most of the hard work of drawing pictures, by using 
information like centre position and radius to draw a circle. 

Measurements of distance (such as circle radius) are in 'user coordinates'. These are 
very small, much smaller than pixels and initially set up so that the shorter side of 
graphics screens is 5000 user coordinates and the longer side proportionally longer 
so that squares come out square when displayedl The area of Results-1 that you will 
see on the display when BASIC 2 starts up is approximately 5000 user coordinates 
square. 
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Point Is 5;6 



Origin 0;0 6 


Positions (such as the location of the circle’s centre) are given as coordinates in the 
form x;y. This specifies the position relative to a reference point within the virtual 
screen, known as the user origin, x is the number of user coordinates to the right of 
the origin, y is the number of user coordinates above the origin. The user origin is 
initially set to the bottom lefthand comer of the virtual screen Its coordinates are 
0;0. (This method of specifying positions is similar to that used on maps and 
graphs.) 

Graphics commands 

Graphics are drawn using a variety of commands. The following examples will give 
you an idea of the facilities available, but refer to Part III for full details. For 
simplicity, numeric constants are used here, but numeric variables or expressions 
are equally valid. 


To draw a circle, use the CIRCLE command. In its simplest form, this is followed by 
three parameters: the position of the circle centre (x;y), followed by the radius. For 
example, to draw a circle of radius 1000, at 1500,1500, in the current output stream: 

Type: CIRCLE 1500; 1500, 1000 n^~l 

To draw straight lines, use the LINE command. In its simplest form, this is followed 
by two pairs of coordinates, separated by a comma, specifying the start and end of 
the line. For example, to draw a line from 50;50 to 2000;0: 

Type: LINE 50; 50, 2000;0 |~P~| 

To draw a continuous line through a number of points, you can use a sequence of 
LINE commands for each section, or specify each point’s coordinates in turn in a 
single LINE command. For example, to draw a triangle: 


Type: LINE 2000;2000, 3000;3000, 4000;2000, 2000;2000[ 



first point '. . # third point . 

second point fourth point (=first) 





























The graphics instructions so far have all used the default line colour, width and 
type. To change these, you can either use the Colours or Lines menus, include the 
appropriate keywords (COLOUR, WIDTH, STYLE) in the command, or change the 
default style by using the GRAPHICS command. 

Select the Colours and Lines menus now, to check on the options available. Try 
changing the colour, line width or type and repeating the previous commands to see 
the different effects. 

Now try using the BASIC 2 facilities, by including the appropriate keywords after 
the position information. For example: 

• To change the width of the line used, add WIDTH followed by a numeric expression 
giving the width in pixels. 

• To change the style of line used, add STYLE followed by a numeric expression in 
the range 0-7. 

• To change the colour of line used, add COLOUR followed by a numeric expression 
in the range 0-15. 

(Note that you should not put a comma before any of these keywords.) 

For example: 

Type: LINE 2000;2000, 3000;3000, 4000;2000, 2000;2000 WIDTH 5 COLOUR 13 
STYLE 3Q±3 

These keywords only override the default line width/style/colour ie for the rest of 
this command. To change the default graphics style, use the same keywords after 
the GRAPHICS command. For example: 

Type: GRAPHICS STYLE 3 WIDTH 5 H=n 

Commands that draw an enclosed shape (such as CIRCLE) can also be extended to 
fill the shape with a solid colour or pattern, by adding the keywords FILL or FILL 
WITH. FILL on its own will fill with the default colour/pattern. To use a different 
pattern/colour, use FILL WITH followed by the pattern number. Refer to the 
appendices in this guide for details of the patterns available. 

For example, to draw a circle at 3000;2000. with radius 1500, line style 4 and colour 
2. filled with pattern number 3: 

Type: CIRCLE 3000;2000, 1500 STYLE 4 COLOUR 2 FILL WITH 3 I~^~I 

Exercises: output 

This section has described how to take greater control of the layout of text, how to 
manipulate windows and produce simple graphics. 

1 Write a program to print 12 different numbers in 4 columns, under different 
headings. (HINT: use commas in the PRINT statements) 

2 Write a program to draw concentric circles centred on 1000; 1000, with radii of 100 
300, and 500. (HINT: use CIRCLE) 
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Solutions 


1 PRINT "Col1","Col2","Col3","Col4" 

PRINT 100, 102, 33, 96.4 

PRINT -3, 44, 45, 16 
PRINT 0, 19, 44444, -3333 

(Your solution will of course use different numbers.) 

2 CIRCLE 1000;1000, 100 
CIRCLE 1000;1000, 300 
CIRCLE 1000;1000, 500 




7 . CONTROL 


In the simplest types of program, each instruction is executed exactly once, in order 
of its position in the program. Most of the examples described above have been of 
this type. While this type of program is very simple to write and understand, it is 
often difficult or impossible to solve quite ordinary problems using it. BASIC 2 
provides a variety of keywords that make programs more versatile, by giving you 
control over which instructions are obeyed. 

These are the 'control' class of keywords. They allow you to: 

- alter the order in which instructions are obeyed ('sequence') 

- repeat instructions or groups of instructions ('repetition') 

- choose between alternative instructions ('selection') 

Examples of each class will now be described and shown in action. 


Altering the order ol execution 


BASIC 2 normally obeys instructions strictly in their order in the program. Thus, the 
following program would print 1 then 2 then 3: 

PRINT 1 
PRINT 2 
PRINT 3 

while the following would print 3 then 2 then 1: 

PRINT 3 
PRINT 2 
PRINT 1 

This predictable, simple behaviour makes programs easy to understand and write. 
Imagine trying to understand a program in which the first, third, fifth and seventh 
lines were executed, then the second, fourth and sixth lines! 

You might find it helpful to think of a BASIC 2 program as a straight railway line, on 
which each sleeper is a BASIC 2 instruction and the position of the locomotive 
indicates which instruction BASIC 2 is obeying at the moment. When the program 
is run, the locomotive starts at one end of the line and proceeds steadily along to 
the other end, crossing (obeying) each sleeper (instruction) in turn, until it comes to 
the end of the track (program). 



'BASIC 2' 



'instruction being executed’ 


'instructions’ 
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This then is the fundamental 'law' of sequence in BASIC 2 programs: instructions 
are obeyed in strict order, from start to end of the program 

BASIC 2 provides a very simple (some would say brutal!) facility to change this, 
using the command GOTO. This is followed by a location, indicating which program 
line should be obeyed next: 

GOTO location 

Execution then continues from that line, as normal. GOTO is like a diversion to 
another part of the program: 
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location can be a line-number, or label. 

A line-number is an integer constant typed at the start of a program line. For 
example: 

100 count = count+1 
line-number 

A label is defined using a LABEL statement: 

LABEL label 

This labels the line with label in much the same way as a line number, label may 
be any name that you could use as a simple numeric variable. For example: 

LABEL carryon 
LABEL addnext 

LABEL finish-up.file.processing 

A line number identifies the line it begins, while a label identifies the next statement 
(or line), so the following are equivalent: 

GOTO 100 
100 PRINT total 

and 

GOTO print-total 

LABEL print-total: PRINT total 

Labels are much better than line numbers, because they allow you to divert to a 
named part of the program, rather than just a rather obscure line number. (Line 
numbers are retained mainly for compatibility with earlier versions of BASIC.) 















The location may be ahead of or before the GOTO instruction, or be even the line 
containing the GOTO instruction. With the destination ahead of the GOTO line, the 
lines between the GOTO and the destination are skipped over as if they did not 
exist. This is mainly used to skip over a part of a program that you don't want to 
use at the moment, for example while developing a program. 

For example, type in and run the following: 

10 PRINT "Who wants to play" 

20 PRINT "PIGGY-IN-THE" 

30 PRINT " MIDDLE " 

40 PRINT "anyway?" 

How can you drop piggy-in-the-middle'? You could delete lines 20 and 30. but you 
might want them again, later. Add a GOTO instruction to skip over them for now, 
check the program, then RUN it to check that the change has worked. 

(With the location before or at the GOTO line, a 'loop' is produced. Loops are 
described under the next heading.) 

GOTO becomes more useful when combined with the decision-making facilities, 
described below. However, once you have learned how to use the full range of 
control facilities, you will probably find it completely unnecessary. (GOTO is really a 
'leftover' from earlier versions of BASIC, retained for compatibility.) 

Another keyword that alters the sequence in an obvious way is the command END. 
When this is obeyed, the program stops immediately. Try adding an END instruction 
to the above example, to prevent the last line being obeyed. 

Repeating instructions 

Many tasks consist of repeated identical (or very similar) actions. For example, 
washing up plates involves washing a dirty plate, washing a dirty plate, washing a 
dirty plate etc, etc! Plotting a bar chart consists of plotting each bar in turn; 
totalling a sequence of figures consists of getting each figure in turn and adding it 
to the intermediate result. 

To simplify producing programs for this type of task, there are a number of ways to 
repeat a group of BASIC 2 instructions, as follows. 

The simplest way of having an instruction obeyed several times is to type it several 
times! Thus, to add three numbers: 

total=0 

INPUT "Number to add";number 

total=total+number 

INPUT "Number to add";number 

total=tota L+number 

INPUT "Number to add";number 

total=tota L+number 

PRINT "TotaL is: ";totaL 

This approach has two major problems: 

- all that typing is rather tedious and error-prone 

- the program is only suitable for adding three numbers - not two, four, five ... fifty! 
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A far more efficient solution is to type the instructions to be repeated just once and 
tell the program to repeat them for you. 

A simple way to do this is by using the keyword GOTO, placing GOTO at the end of 
the sequence you want repeated, with the first line of the group as its location. The 
totalling program now becomes: 

tota1=0 
LABEL Loop 

INPUT "Number to add";number 
total=total+number 
PRINT "Total is: ";total 
GOTO Loop 
PRINT "The end" 

When this program is run, each line is executed in order, until the GOTO instruction 
is obeyed, when execution continues from the label 'loop' until the GOTO 
instruction/etc etc. 

The GOTO command has produced a ‘loop’ - a group of instructions that are 
repeated. The end of this loop is clearly marked by the GOTO command, but the 
beginning is not so obvious. It is indicated by the location in the GOTO command. 

In the above example, the loop consists of the third, fourth and fifth lines: 

tota1=0 
LABEL Loop 

INPUT "Number to add";number 
total=total+number 
PRINT "Total is: ";total 
GOTO Loop 
PRINT "The end" 

To make it clearer, you could indent lines in the loop, by typing them with leading 
spaces: 

tota1=0 
LABEL Loop 

INPUT "Number to add";number 
total=total+numbe r 
PRINT "Total is: ";total 
GOTO Loop 
PRINT "The end" 

If you haven't already done so, type and run this program. Note how "The end” is 
never printed (showing that the last line is never obeyed) and the program never 
stops! 

This is because the loop has no exit - once it is started, it will keep on repeating. 
To stop the loop, you must stop the program, by pressing Ctrl-C. While this is 
acceptable where there is a single loop at the end of the program, many tasks will 
require more than one loop or loops in places other than at the end of the program. 

BASIC 2 provides a number of keywords to allow you to construct rather better 
loops. These loops are superior in two main ways: 

- they have convenient, logical ways of finishing 

- they have a clear-cut beginning and end 




The latter advantage may seem trivial, but once you start writing or trying to 
understand programs of a moderate size, you'll soon see how life is much easier 
when you can see the start and end of each loop at a glance. 

Loops can finish in two ways: 

- after a fixed number of repetitions 

- when a key event happens, such as two variables becoming equivalent 

The first type of loop is provided by the two keywords FOR and NEXT and is usually 
called a 'FOR loop', for the obvious reason! 

This loop is started by the command FOR, which takes the form: 

FOR counter-variable = start-value TO end-value 

(There are a number of other variations, but this is the simplest) 

counter-variable is a numeric variable; start-value and end-value are numbers, 
numeric variables or numeric expressions. 

For example: 

FOR index = 1 TO clients*2 

The loop ends with the command NEXT, so a simple loop might be: 

FOR index = 1 TO 5 
PRINT index 
NEXT 

This simple FOR loop works as follows: 

a When the FOR instruction is first obeyed, evaluate and store start-value and 
end-value. Set counter-variable to start-value. If counter-variable is greater than 
end-value skip over the whole FOR loop (ie to the next instruction after the NEXT) 
and carry on from there. Otherwise: 

b Obey the instructions in the body of the loop (ie between the FOR and NEXT 
instructions), in order. 

c When the NEXT instruction is obeyed, add 1 to counter-variable and compare it to 
the stored end-value. If counter-variable is now greater than end-value, leave the 
loop and obey the instruction after the NEXT. Otherwise, start over again with (b) ie 
obey the instructions in the body of the loop again, in order, then increase 
counter-variable by 1 when NEXT is obeyed, compare it with end-value etc. etc, 
until the FOR loop finally finishes. 

This type of loop is ideally suited to many repetitive tasks, where the number of 
repetitions required will be known at the start of the loop. For example, to input 
values to initialise an array: 

elements = 10 
DIM value(elements) 

FOR a = 1 TO elements 
INPUT "Type value",number 
value(a) = number 
NEXT 

The other types of loop and variations of the FOR loop are described in Part m (w 
FOR, WHILE, REPEAT). m VSee 
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Making decisions 

All the programs and programming facilities described so far have been rather 
mechanical, allowing you to produce programs that make your computer behave as 
little more than a calculator. What about the so-called 'intelligence' that computers 
are meant to have or at least imitate? The key facility missing so far is the ability to 
make decisions. 

Making decisions is such a fundamental aspect of human behaviour that it is quite 
easy to overlook. Almost every moment, you are making decisions; conscious or 
subconscious, trivial or vital (is it time to catch the train? shall I skip this bit of the 
book?). 

Human decision-making can be incredibly subtle, but decision-making in programs 
is largely a matter of testing the relationship between two items of information and 
obeying a different group of instructions, depending on the relationship found. 

This may sound rather mechanical, but many human decisions can be expressed in 
a similar fashion. For example, on the subject of 'is it time for lunch?’: 

- If it’s lunch time, then I'll eat my lunch 

or - If it's lunch time and I’m hungry, then I’ll eat my lunch 

or - If it’s lunch time and I'm hungry and I've brought a lunch that I like and I don't 
have to do anything else, then I'll eat my lunch 

While computers don't get hungry, nor eat lunch (yet), the fundamental principles 
are similar and so are the words (keywords) used. 

The simplest decision-making structure uses the keywords IF and THEN. IF is 
followed by a 'condition' that specifies a relationship between two items of 
information. After this is THEN, followed by the instructions to obey if the 
relationship stated in the condition is true: 

IF condition THEN instructions 

For example: 

IF apples = 0 THEN PRINT “No apples!" 

condition instructions 

If the condition is true, the remainder of the line will be obeyed, followed by the 
next program line, etc. 

If the condition is not true, the remainder of the program line is ignored and the 
next program line will be obeyed. 

Note that the whole 'IF structure' (from the IF to the last instruction depending on 
the condition) must be included on a single program line. If you want to make 
several instructions depend on the condition, you must include them all on the same 
line. (This is a case where 'multi-statement lines’ can be very useful.) 

Note that the equals sign used in a condition does not change the value of any 
variables (contrast this with the assignment instruction, apples = 0). 

To see IF in action, run the following program: 




LABEL again 

INPUT "Number of apples (0 or more)";apples 
IF apples = 0 THEN PRINT "No apples!" 

GOTO again 

Try the effect of typing different numbers in reply to the prompt. Only when you 
type 0 will the message “No apples!" be displayed. The program is making a 
decision based on the information you supply; whether or not to display the 
message. To stop the program, press Ctrl-C. 

The key to an IF structure is the symbol between the two information items in the 
condition. It is this that states the relationship between the items, the truth of 
which determines which instructions are obeyed. In the above example, the symbol 
used was the equals sign (=): 

IF apples^0 THEN PRINT "No more apples!" 

relationship symbol 

There are two other symbols, the ‘greater than' symbol, “>" and the ‘less than’ 
symbol, "<". 

For example, to print a message when there are more apples than you can carry 
(say, 10), change the IF structure to: 

IF apples > 10 THEN PRINT "Too many apples to carry!" 

You may find it helpful to translate the above into English: 

If (the number of) apples (is) greater than 10 then print “Too many apples to carry!" 

The items being compared must both be numeric or both string. They may be 
constants, variables or expressions. 

As mentioned above, you can make more than one instruction depend on the 
condition. To do this, just add the other dependent instructions to the end of the 
line containing the IF structure. Remember to separate the instructions with colons 
(:). For example: 

IF apples > 10 THEN PRINT "Too many apples to carry!": apples = 10 

This line checks if you've specified more than ten apples. If you have, you've got too 
many, so it sets the number of apples to 10 and warns you what it’s done. 

This tends to produce rather long program lines which are difficult to check and 
understand. There are better solutions, described in Part in. 


Usually, IF produces a minor diversion, depending on whether the test relationship 
is true or false: if false, the rest of the line is ignored and the .next line is obeyed; if 
true, the rest of the line is obeyed, followed by the next line: 
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However, by making IF control a GOTO instruction, you can make the impact of the 
decision as major as you .want. This produces a 'conditional branch’, which can 
even make the program 'split' and take one of two quite different paths, depending 
on the condition: 



For example: 

INPUT "Do you want to buy cats (Y or N)";answer$ 

IF UPPER$(answer$) = "N" THEN GOTO buydogs 
LABEL buycats 

INPUT "How many cats do you want";cats 
GtC 

LABEL buydogs 

INPUT "How many dogs do you want";dogs 
etc 

In this program, after the IF instruction is obeyed, execution will continue either 
from the label 'buydogs' or 'buycats', depending on the value of answers. 

There are several other, more complex, forms of IF structure, which are more 
convenient for programming certain types of decision. However, the simple form 
described here should suffice for your present needs. 

You can also combine looping with decision-making (the loop finishes when a test 
becomes true or false). 

These facilities are described (you guessed it) in Part m. 

Exercises: control 

1 Write a simple program to print your name over and over again. This should only 
take two lines. (HINT: use GOTO) 

2 Assuming that a leap year is a year which can be divided by 4 without any 
remainder (which is nearly true!), write a program that asks the user to type a year 
number, then displays a message indicating whether or not it is a leap year. (The 
program need not loop.) 

3 The following program is meant to display “Happy birthday” if the day is the 21st, 
but it contains one error. Correct it and check the corrected version by running it: 

INPUT "Which day of the month is it (1-31)";dayS 
IF day$ = 21 THEN PRINT "Happy birthday" 




































4 Write a program to display the 'n' times table, where the user types 'n' when the 
program is run. 

Solutions 

1 10 PRINT "J S Bach" 

GOTO 10 

2 INPUT "Year";year 

residue = (year/4) — FL00R(year/4) 

IF residue = 0 THEN PRINT "That is a Leap year" 

IF residue > 0 THEN PRINT "That is NOT a Leap year" 

3 The test in the second line is attempting to compare a string variable with a 
numeric constant; strings and numbers cannot be compared directly! Either change 
day$ to day in both lines, or 21 to "21” in the second line. 

4 INPUT "Which times tabLe (1-12)";number 
FOR muLtipLe = 1 TO 12 

PRINT muLtipLe;" times ";number;" is ";muLtipLe*number 
NEXT 
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8. CONCLUSION TO PART II 

The aim of this part of the guide was to teach you the fundamental concepts and 
techniques needed to understand and to program in BASIC 2. 

You should now know how to: 

- use BASIC 2 as a calculator 

- analyse a task into its parts 

- store and process different types of information 

- type, change, store and use programs 

- make parts of a program repeat themselves 

- write programs that make decisions 

The remaining parts of this guide assume a reasonable familiarity with these 
concepts, going on to present BASIC 2 in its full glory. Now might be the best time 
to go back over this part and do the exercises. If you have problems with any of 
them, try the HINTS, or re-read the appropriate section. 
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PART III: PROGRAMMING WITH BASIC 2 


This part of the manual describes the main elements of BASIC 2, 
classified as explained in Part II, into the following areas: 

- program development tools 

- information types, storage and sources 

- manipulating information (numbers and text) 

- displaying and printing information: text and pictures 

- using discs for information storage 

- program structure, control and design 

This Part concludes with a 'practical' chapter, showing you how to 
design and produce a fairly significant program that will show off 
many of the facilities of BASIC 2 described here. 

While you can of course read this Part through from first to last in 
page order, this is not necessary. Feel free to skip over any sections 
that seem too difficult or irrelevant to your interests at this stage. 

For a review of the facilities provided in each area, read the relevant 
chapter's introduction. 

If you are unfamiliar with any of the topics or concepts raised here, 
refer to Part II or to a suitable BASIC tutorial manual. In particular, 
example instructions and program fragments are used to illustrate 
the use of the BASIC 2 facilities. To understand these examples, you 
will need to be familiar with the following small subset of BASIC 2 
concepts and facilities: 

- string and numeric variables and constants 

- arithmetic operators and expressions 

- assignment to variables 

- the commands PRINT and INPUT 

- the FOR loop 

- the IF statement 

- simple relational expressions (using >. <. =) 

If you are not, you are recommended to (re)read Part II for this basic 
BASIC 2 groundwork! 
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1. PROGRAM DEVELOPMENT TOOLS 


This chapter describes the BASIC 2 facilities provided for preparing and using 
programs 

These will be considered as the following four groups: 

- preparing programs 

- examining programs 

- filing programs 

- using programs 

These facilities are used by selecting menu options with the mouse, pressing special 
keys or typing commands in the Dialogue window. 

Many menu options can also be selected more quickly, by pressing single keys. 

Where this is the case, the key corresponding to the option is displayed in the 
menu, at the righthand end of the option line. 

Each group will now be described in turn, after first defining the basic structure of a 
BASIC 2 program. 

Program structure 

1 

A BASIC 2 program consists of one or more 'program lines'. Programs can be 
manipulated whole (eg deleted, used, saved) or changed, a line at a time or even a 
character at a time. 

A program line consists of one or more 'statements' (or instructions), ending with a 
I g | character. Statements must be separated by colons (:). The line may start 
with a line-number, which is a decimal integer constant that can then be used to 
refer to this line in commands. (This is all that the line number does; it does not 
dictate the line's position within a program, unlike earlier versions of BASIC.) 

A statement consists of a command, which is a BASIC 2 keyword, followed by the 
information it uses, called its parameters, which may be optional. A line is thus 
defined as: 

[line-nUmber] command [parameters] [: command [parameters]...] 

Programs are stored on disc as named files. The number of these that you can store 
on a disc is only limited by its storage space and any limitations imposed by the 
operating system. 

You can only have one program in memory at a time, however. This program is 
called the ‘current program' and is the only one that BASIC 2 can use (execute, 
change, display etc) directly. To use a program other than the current program, you 
must first read it from the disc so it becomes the current program. 

Preparing programs 

A program is written (or changed) using the keyboard and mouse, in the Edit 
window. 
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If the Edit window is displayed, just move into it. 

If the Edit window is not displayed, you can open and enter it in one go, by using 
the command EDIT, or the 'edit 1 option in the Program (or Edit) menu. 

The Edit window displays the current program and provides facilities that fall into 
the following main groups: 

- typing: inserting, replacing and deleting single characters 

- moving through and examining the current program 

- deleting, moving and copying parts of the program 

You will probably find the Edit window easier to use if you enlarge it, either by 
dragging its size box or by clicking on its full box. 

To return to the Dialogue window, click anywhere inside it. To remove the Edit 
window from the display, you can close it - this has no effect on the current 
program. 


Typing 


Anything you type within the Edit window will be stored in the current program. It 
follows that to get BASIC 2 to obey commands, you must leave the Edit window 
and type them in the Dialogue window. You can, of course, use menu options while 
in either window. 

Characters you type will usually be inserted, at the cursor position, pushing existing 
text to the right to make room. 

To switch to replacing characters at the cursor, press I ins I once; to return to 

inserting, press I in» I again. 

To delete characters just typed (to the left of the cursor), press I «o«i 1 . 

To delete characters at the cursor, press I pjj» 1 If held down, this will delete to the 
right. 


Moving 


Text is typed at the position indicated by the text cursor, which can be moved (a 
character/line at a time) by using the cursor keys. Alternatively, you can point to the 
required position with the mouse and click (you do not have to drag the text cursor). 

By moving the cursor, you can change any part of the program, rather than just the 
line you are typing. 

If the program is too large to fit within the window, you can scroll the window to 
view parts that are not visible. To do this, you can simply hold down the 'up 1 or 
‘down’ cursor key (as appropriate), move the scroll bar with the mouse, or use the 
following keys: 



move up a 'windowfuT 
move down a 'windowful 1 
move to start of program 
move to end of program 














Changing parts of the program 

To copy, delete or move a part of the program, you must first mark its limits, by 
moving the text cursor to its start and selecting the 'Start area’ option from the 
EDIT menu, then moving to its end and selecting the 'End area' option. 

To delete the area marked, simply select the 'Delete area' option. 

To copy or move the area, move the text cursor to the destination required and 
select the appropriate option. 

To redefine the marked area, just define the correct start and end points. 

To cancel a marked area, use the 'Cancel area’ option. 

To ‘tidy up' the line numbers used in a program, use the 'Renumber' option in the 
Edit menu. This allows you to change all line numbers used so that they are 
consecutive, with a particular start and increment. 

To replace the current program with one from disc, use the File menu option 'Load'. 

To delete the whole program, use the Program menu option 'New', or return to the 
Dialogue window and use the command NEW. 

Examining programs 

Before you can examine a program, you must load it into memory ie make it the 
current program. 

To examine the program on the display, use the Edit window as described above. 

To print the entire program on a printer, use the 'List' option from the Program 
menu. 

Filing programs 

The current program can be filed on disc or read from disc, using menu options, as 
follows. Most of these use a filename, which may be any name that is valid for the 
operating system. If the name does not include a filetype extension, '.BAS' will be 
assumed. 

The 'Save' option saves the program on disk as text (as it would be displayed or 
printed). This allows you to save a BASIC 2 program so that it can be used by other 
programs, including other versions of BASIC, text editors, etc. 

To read a program from disc so that it becomes the current program, use the 'Load' 
option from the File menu. 
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Using programs 

To obey the current program, use the Program menu’s ’Run' option or the command 
RUN. 

To stop a program which is running, press Ctrl-C, or select the Program menu 
option ’Stop’. 

To restart a stopped program, use the command CONT or the Program menu option 
‘Continue’. 




2. INFORMATION TYPES, STORAGE AND INPUT 





This chapter describes the types of information that programs can use and how that 
information is obtained (input), stored (assignment) and handled (variables). 

For a description of manipulating information (operators, expressions, functions etc), 
see the two subsequent chapters. 

Types of information 

As far as BASIC 2 is concerned, there are two main types of information: numbers 
(numeric information) and text (string information). In general, these two types are 
quite distinct and incompatible, having different behaviour and keywords associated 
with them. (Facilities are however provided to convert between the two types, 
where appropriate.) 

Numbers 

The numbers used by BASIC 2 can be expressed (typed) in a variety of forms. 
Regardless of how they are expressed, once they are used (in a command or 
assigned to a variable) the details of their original form and source are lost. 

The simplest forms are the 'unsealed numbers': integers and real numbers. 

An integer is a whole number without a fractional part, which can be positive, 
negative or zero. Examples are 444, +3, 0, -9999. Integers are sometimes called 
'counting numbers'. 

A real number is similar to an integer but has a fractional (decimal) part after the 
decimal point character, for example: 444.123, +3.0000000001, 0.0, -9999.9. 

BASIC 2 stores these two types of numbers in the same way. Some other versions 
of BASIC make you choose between using integer and real variables, if you want to 
take advantage of the fact that integer arithmetic is faster than real arithmetic. 
BASIC 2 saves you the trouble, by using integer arithmetic automatically whenever 
it can. 

BASIC 2 facilities that need integer values automatically convert their parameters 
from real values to the equivalent integers, when required. 

Both forms of unsealed number will probably already be familiar to you from 
everyday use, but note that the numbers used must not include commas or spaces, 
which you may be used to seeing in expressing large numbers. 

Probably less familiar (unless you have a scientific background) are ‘scaled numbers' 
or ‘scientific format' numbers. In these, the number is expressed as a positive or 
negative decimal number multiplied by the number 10 raised to a positive or 
negative power. In BASIC 2, they take the form n.imvE[sign]nn. For example. 1.0E6 
denotes 1 million (1 followed by 6 zeroes), while IE-3 denotes one thousandth (1 
divided by 1000). 

Scaled numbers are mainly used for expressing very large and very small numbers 
in science and technology. For example, the speed of light is approximately 2.998E8 
metres per second. 
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Finally, you can use 'based numbers', to express numbers in binary (to base 2) or 
hexadecimal (to base 16). Binary numbers start with &X followed only by Is and Os. 
Hexadecimal numbers start with & followed by numbers in the range 0-9 and 
letters A - F (corresponding to 'digits' of 10 - 15). Example binary numbers are 
&X0 (0) and &X11111111 (255); example hexadecimal numbers are &FF (255) and 
&10000 (65536). 

The based numbers are taken as 2's complement integers, so that their values are in 
the range: 

Minimum Maximum 

-2,147,483.648 +2.147,483,647 

&X10000000000000000000000000000000 &X01111111111111111111111111111111 

&80000000 &7FFFFFFF 

Based numbers will mainly be of interest if you are used to low level programming 
with minicomputers or microcomputers. 

Typical numbers in each of these forms are as follows: 


Unsealed 

Scaled 

Binary 

Hexadecimal 

0 

0E0 

&X0 

&0 

100 

1E2 

&X01100100 

&64 

-100 

-1E2 

&X11111111111111111111111110011100 

&FFFFFF9C 

100.1 

1.001E2 

- 

- 

0.023 

2.3E-2 

- 

- 


Remember that once a number has been input and stored in a numeric variable, its 
original representation is forgotten. 

Strings 

A string (or 'text string’) is a sequence of text characters, between 0 and 4096 
characters long. 

A string constant must start and end with double quotes (") to distinguish it from a 
number or variable name. When typing a string in reply to a prompt, there is usually 
no need for quotes (but see INPUT) - typed characters are interpreted as a number 
or string entirely according to the type of variable being used in the input 
instruction. 

There are 192 different text characters (or 95, in an American GEM system). 
Probably the most familiar of these are the numbers, letters, common symbols and 
punctuation marks which appear on typewriter keyboards as well as on your 
computer keyboard. There are however many other characters, including accented 
European letters and the greek alphabet. Each character is uniquely identified by its 
character code, a number in the range 0 to 255. For a full list of characters and their 
codes, see Appendix I. 

Typical text strings are: 

mi 

"and did those feet" 

"Catherine Louise, spinster of this parish" 

"23" 




The first string has zero length and is called a 'null string’. The last string is only a 
string because it is enclosed in quotes; without the quotes it would of course be the 
number 23. 

Most of the characters that you will want to use can be typed directly from the 
keyboard. Other characters can be 'created' using BASIC 2 functions. 

Information storage (variables) 

' Most programs use information supplied while the program is running, from sources 
such as the user's replies to prompts, disc files, or the computer’s operating system. 
This information is usually obtained in one instruction and used in a later one - it is 
'stored' in the meantime, using 'variables’. 

A variable is simply a name, invented by the writer of the program, which is used to 
store and refer to information, within the program. BASIC 2 reserves memory for the 
information each variable represents and remembers the variable’s name as linked 
with it. 

The simplest way that information is stored in a variable is 'assigning' to it, in an 
assignment statement, which takes the form: 

variable = information 

The fundamental types of information have already been described. The types of 
variable will now be described, followed by further details of assigning information 
to variables. 

Variable names 

BASIC 2 leaves the choice of variable name largely up to the programmer. The 
shortest variable name is 1 character, the longest is 40 characters. The name must 
not be the same as a keyword (a full list is given in the appendices). Capitals and 
small letters are considered equivalent in variable names. The name may include 
any of the following characters: 

- any of the letters 'a' to 'z' (capital letters may be used, but they are converted to 
small letters automatically) 

- any of the accented letters and greek letters (see Appendix I). These may 
however cause problems when using certain printers to list programs. 

- the underline character _ 

- numbers 'O' to '9' in any position other than the first character 

- % !# or $ but only as the last character. $ denotes a string variable. 

For example, the following are valid variable names; 

a 

sane_mind_and_body 

Surnames 

part0ex% 
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But the following are riot: 


0a 

- starts with a numeral 
stop 

- identical to a keyword (STOP) 
get#lost 

- # used other than at the end of a name 

the_life_and_times_of_an_ordinary_morta 1$ 

- more than 40 characters long 

titles held 

- name includes a space 

Remember that capital and small letters are considered equivalent in variable 
naming, so that the variable 'Surnames' is the same as 'surnames', 'SURNAMES' 
etc. 

Lifetime of variables 

Once a variable has had a value assigned to it. this will be retained until either 
another value is assigned to that variable or the program's variables become 
undefined. This happens when you: 

- RUN a program 

- LOAD a program 

- leave BASIC 2 

If you use an undefined variable, its value will usually be taken as 0 (for a numeric 
variable) or the null string "" (for a string variable). You can however choose to have 
this treated as an error (see OPTION TRAP). 

Numeric variables and precision 

Any variable that does not end in a $ is a numeric variable. 

Numeric variables have the same range and precision as described previously for 
numbers. 

Numeric array elements and record fields normally have the same precision as 
numeric variables, but you can also define them using 'storage classes', which 
makes them use less memory, by restricting the range of values that can be stored 
(See DIM and RECORD.) 

String variables 

Suing variables are distinguished from numeric variables by having $ as their last 
character. The maximum number of characters that can be stored in a string 
variable is 4096; the minimum is zero (the null string. ""). Characters with codes 
anywhere between 0 and 256 can be stored in strings. For a full list of characters, 
see Appendix I. 

The string variables defined and used in this way are 'variable length string 
variables', because the length of the information they represent can vary (between 0 
and 4096 characters). 



You may also define 'fixed length string variables' for use as array elements and 
record fields. These are discussed later. 

Facilities are also provided to treat parts of a string variable (or expression) 
independently, as 'substrings'. These are described further below and in the chapter 
on processing text. 

Structured storage (arrays and records) 

Variables are normally quite independent, but you can organise them into two types 
of larger structure: 'arrays' and ‘records'. 

Arrays are mainly suited for information which is already structured, such as lists or 
tables. 

Records are mainly used for grouping related items of information into a compact 
form, for storage in disc files. 

Arrays 

An array is a collection of variables with the same name. They are referred to by this 
name, followed by an 'array index' in brackets. The anay name can be any valid 
variable name, for example: 

cats (.array-index) 
a$( array-index) 

transactions_to_dat e#(. array-index) 

You can use round brackets ( ) or square brackets C 3 for the array index. You 
may prefer to use square brackets, as this helps to distinguish anay variables from 
function calls, but within this guide, round brackets will be used. 

The simplest form of anay is a single-dimensional anay (or 'vector'), in which the 
first variable in the list ('element') has an anay index of 0, the second an index of 1 
and so on. The array-index in this case would be a single numeric constant, variable 
or expression, for example: 

cats<moggy*2+1) 

An anay should usually be defined before use, using the command DIM. This is 
followed by the name of the array and a specification of the number of elements (the 
array’s ‘dimensions'), in brackets: 

DIM name( dimensions) 

You may define several arrays in a single DIM statement by separating them with 
commas. For example: 

DIM cats(10), dogs(5) 

This use of DIM produces an array of whose first element is numbered 0. To have a 
different starting element, specify the dimensions as a range of elements, using TO: 

DIM cats (.first TO last ) 

The first element in the anay will be numbered first, the last will be numbered last, 
first must be less than last. Negatively numbered elements are allowed but 
elements must be in the range -32768 to 32767. 
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An array can have as many dimensions as can be fitted on a program line! Each 
dimension is specified separately in the DIM instruction, separated by commas. For 
example, to specify a three-dimensional array of 10x10x5 called 'temps’: 

DIM temps(1 TO 10, 1 TO 10, 1 TO 5) 

v -V- 7 '- Y - 7 '-v- 7 

1st dimension | 3rd dimension 
2nd dimension 

(This array might for example be used to store the average temperature of each 
cubic metre of air within a sports hall measuring 10x10x5 metres.) 

Each dimension can be specified using a single number (producing elements 
numbered 0 to n). or using TO to specify the range, as described above. 

You must not dimension an array more than once in a program. You do not have to 
dimension an array before using it, but this is a good habit to get into. If you use an 
array before dimensioning it, the array will be set up with the required number of 
dimensions, each of which is taken as 0 TO 10. 

Elements in an array are generally used as individual variables - the array is not 
usually processed as a single entity. An array is simply a way of organising variables 
for your convenience. A typical use is within a FOR loop, which can step through 
each index value to access each element in turn. 

Storage classes 

When you define an array, you reserve space to store the value for each element. If 
you use arrays with many dimensions or elements, your program can run out of 
memory quite quickly. To help you avoid this, you can specify a 'storage class' for a 
numeric array when you define it, which limits the range of values permitted for 
each element and so uses up less memory. 

The storage class is specified in the DIM instruction, as follows: 

DIM array-namei dimensions ) storage-class 

The storage class applies to all elements in the array. The classes allowed are: 


Class 

Value range 

Memory used per element (bytes) 

BYTE 

-128 to +127 

1 

UBYTE 

0 to +255 

1 

WORD 

-32768 to +32767 

2 

UWORD 

0 to +65535 

2 

INTEGER 

-2147483648 to +2147483647 

4 


Each element in a numeric array would normally use 5 bytes. So, for example, by 
changing: 

DIM grid(1 TO 10, 1 TO 10) 
to: 

DIM grid(1 TO 10, 1 TO 10) BYTE 

You would save 400 bytes (10*10 elements, saving 4 on each). 

Of course, by defining the storage class as BYTE, you also restrict the values that 
can be stored, to the integers -128 to +127! 
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Fixed length string variables 

V 

For a string array, memory space can be saved by using the keyword FIXED, 
followed by a numeric expression specifying the maximum length of each element: 

DIM namdSf. dimensions) FIXED length 

For example: 

DIM firstname$(20) FIXED 15 

length can be any numeric expression in the range 1 to 4096. (The memory savings 
on string arrays are more difficult to predict.) : 

The elements in a string array defined like this are created immediately, with the 
maximum length specified, filled with nulls (code 0). These are 'fixed length' string 
variables. Their behaviour is somewhat different to that of normal (variable length) 
string variables, as will be described below. 

Records 

If you are processing items of information which are closely related, you may find it 
convenient to use the data structure known as a 'record'. Record structures are 
mainly provided to make creating and processing of disc files easier, but can be 
useful in other areas too. 

A record structure is not a variable, but a sort of template, used to manipulate 
different parts of a string as if they were separate variables. 

A record structure is defined using the RECORD command, which takes the form: 

RECORD record-name ; fields 

The record-name is any valid variable name, without type suffix or array 
organisation. It is entirely distinct from any variable or label with the same name, so 
you could, for example, use a record structure, variable and label with the same 
name. 

The fields part consists of one or more field parts, separated by commas. A field can 
be any valid variable name (including string), or single dimensional array of the 
same: 

name 

nameC dimension) 
names FIXED length 
namd& C dimension) FIXED length 

Numeric fields and numeric array fields can be qualified by the same storage classes 
as arrays, to save memory. Without a storage class, each numeric field or numeric 
array element will take eight bytes. 

Field names are local to a record structure, so you can use the same name for fields 
in different records. 

For details of dimension and storage-classes, see under the previous headings, but 
remember that only single-dimensional arrays may be used. 

Note that the length of string or string array fields must be specified using the 
FIXED keyword. 
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Once a record structure has been defined, it can be used to treat part of a string as 
if it were a separate variable. This is done by appending the record and field names 
to the string, separated by dots, thus: 

string, record-name, field-name 

This combination of string, record name and field name can be used exactly as the 
variable type corresponding to the field's type. For example: 

Declaring the structure: 

RECORD person; namelS FIXED 20, salary UWORD; grade$(2 TO 5) FIXED 1 

person 










ss 

£2. 


in. 






</* 

name1$ 

salary 

CD 

1 

o 

1 

<D 

■§ 

<D 

"O 

2 



o> 

o> 

o> 

O) 


You must initialise a string before you can use a record structure to assign to its 
fields. The recommended way of doing this is to use the STRINGS function to set it 
to all null characters (the character with internal code 0). 

STRINGS (number,value) produces a string number characters in length, each 
character having internal code value. 

Assigning to a record structure: 

First initialise the string which will hold the record - r$. 

r$=STRING$(26,0) 

then assign to the individual fields: 

r$.person.namelS = "Old MacDonald" 
r$.person.salary = 5000 
r$.person.gradeS(3) = "C" 

Using a field as a variable: 

PRINT r$.person.namelS 

PRINT "Weekly salary approximately";r$.person.salary/52 
etc 

Record field names are entirely distinct from other variable names, so that for 
example person.namelS, company.namelS and namelS are all distinct and 
separate. 

Memory usage 

To summarise, the memory used by each type of variable and storage class is: 


Type 

numeric 
numeric field 
FIXED array/field 
BYTE array/field 


Bytes used 

5 

8 


defined length 
1 










UBYTE array/field 
WORD array/field 
UWORD array/field 
INTEGER array/field 


1 

2 

2 

4 


Additional memory is also used for each variable's name. 

String array elements can be variable length or fixed length. If all elements are 6 
bytes or less, less memory will be used by fixed length elements. 

The amount of memory free at any time can be determined using the function FRE, 
which returns the number of bytes free: 

PRINT "Free memory is";FRE 

Unlike some other versions of BASIC, all the free memory is collected together 
(known as garbage collection) when you use FRE. You do not have to take any 
special action. 


Assignment 


As described previously, information can be stored in variables by assigning it, using 
the equals sign: 

variable = information 

information need not be a constant, it can be a variable, for example: 
count = total 

or even an 'expression', for example: 

fruit = apples + oranges 

(An expression is a combination of constants, variables, operators and functions, 
used to calculate the information rather than state it directly. For details, see the 
chapters on manipulating information.) 

The information in a variable is not fixed (hence the name) - you can assign to the 
variable as often as you like. You can even use a variable in the expression which is 
being assigned to it (its value will remain the same until the entire expression has 
been evaluated). 

The values held in two variables can also be swapped directly, using the command 
SWAP: 

SWAP variable-1, variable-2 

String variables can only be assigned string information (text). Similarly, numeric 
variables can only be assigned numeric information (numbers) ie the two sides of 
the assignment statement must be of compatible types. 

Thus, the following are legal: 

string-variable = string-information 

numeric-variable = numeric-information 

While the following are not legal and will fail, producing an error: 
string-variable = numeric-information 
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numeric-variable = string-information 

(There are functions that can be used to get around this problem, by explicitly 
converting strings to numbers and vice versa. See the chapters on manipulating 
information.) 

Assignment to numeric variables and assignment to stnng variables follow different 
rules - each will now be described in turn. 

Assigning to numeric variables 

Range 

Numeric variables and numeric storage classes can hold information up to a 
maximum size, as described previously. If the information being assigned is too 
large, the assignment will fail and an error will result, otherwise the assignment will 
succeed. 

Usually, information will be stored in a variable exactly as assigned to it, as you 
would expect. However, this may not be the case, due to loss of precision or 
conversion errors, as follows. 

Loss of precision (rounding) 

Numeric variables and storage classes each have a fixed precision, as described 
previously. Information which is more precise than this will suffer a loss of precision, 
without error, to make it 'fit'. This process is called 'rounding'. 

Rounding takes place at the first digit which will not fit. It is most easily explained 
for assigning to variables (array elements or record fields) with a storage class of 
WORD, BYTE or INTEGER. These variables can only store whole numbers, so 
rounding takes place at the first decimal place. If this is 5 or greater, the magnitude 
of the integer part is increased by 1. For example: 

4.4 rounds to 4; 4.5 to 5 
-4.4 rounds to -4; -4.5 to -5 

A similar process occurs when assigning a value to an ordinary numeric variable, if 
the value has more digits than the variable's precision can accommodate (typically, 
9 digits). In this case, the rounding occurs at the first digit that will not fit. 

Conversion errors 

The number system used by almost all modem computers is binary (base 2), while 
we generally use decimal (base 10). This means that most computers have to 
convert decimal numbers to binary for storage, then convert them back again for 
output. This process is entirely trouble-free when using whole numbers, but can 
produce slight problems when manipulating numbers with a fractional part, since 
many fractions that can be expressed exactly in decimal cannot be expressed 
exactly in binary. 

This difference produces a ‘conversion error', which will generally only affect the 
least significant digit of a floating point number and be corrected by rounding. 
Conversion errors can however accumulate and become significant in complex or 
lengthy calculations. 

BASIC 2 operates with this number system, called ‘binary precision'. 




Binary precision will be sufficiently accurate for most programs and has the 
advantages of being quick and using little memory. 

Assigning to string variables 

Simple assignment 

A string expression can be assigned directly to a string variable using the equals 
sign: 

string-variable = string-expression 

This will completely replace any information currently held by that string variable. 

Like numeric variables, string variables can store a limited amount of information. 

Ordinary string variables can be assigned strings between 0 and 4096 characters 
long. Attempting to assign a longer string will cause an error. 

A fixed length string variable (see FIXED, above) can store strings up to the number 
of characters specified when it was defined. Attempting to assign a longer string 
will not cause an error, but simply assign as many characters as are allowed (from 
the start, or lefthand end, of the string). Assigning a shorter string will fill the 
remainder of the fixed length string variable with trailing nulls. These nulls will 
normally be discarded when using the variable, so it will behave almost like an EalSSi& 

ordinary string variable. To assign it complete with trailing nulls, use the function 
WHOLES: 

string-variable = WHOLES (.fixed-length-string) 

Justified assignment 

You can assign to a string variable without changing its current length (even if it is 
a variable-length variable), by using the LSET and RSET commands. These 
left-justify and right-justify the string assigned, to the current length of the variable: 

LSET variable = expression 

RSET variable = expression 

LSET assigns expression to variable, truncating it if longer than variable, padding it 
with trailing spaces if shorter. Note that padding is with spaces whereas a fixed 
length string would normally be padded with nulls. 

RSET assigns expression to variable, truncating it if longer than variable, padding it 
with leading spaces if shorter. 

Assigning to substrings 

You can also assign to string variables piecemeal, by assigning to 'substrings' or 
'record fields’, or using the MID$ command. 

Using record fields, as already described, you can assign strings or even numeric 
information to any position in a string variable. This will not be described further 
here (see RECORD). 

Using substrings, you can assign characters to any position within an existing string 
variable. Note that this does not alter the length of the string. 

Substrings are used in assignment as follows: 

variable^ range} = string-expression 
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where variable is the string variable to assign to and string-expression is the string 
to assign from, range specifies where to start assigning and how many characters to 
assign, as follows: 

start TO end 

- assign characters to positions start to end of variable 
start TO 

- assign characters to position start to the end of variable 
TO end 

- assign characters to the beginning of variable to end 
start 

- assign a single character to start in variable 

A positive position specifies the nth character from the start of the string (first 
character = 1). A negative position specifies the nth position from the end of the 
string (last character = -1). 

You can also use MID$ to assign to substrings. This has been provided mainly for 
compatibility with earlier BASICS. It is used as: 

MI 0$ ( variable, start[, length]) = string-expression 

variable is the string variable to assign to. start is an integer expression indicating 
at which character of variable to start assigning (1 = first character), length 
specifies how many characters to assign, from the start of string-expression, if 
omitted, characters will be assigned until the end of either the variable or the 
string-expression. 

Getting information (input) 

Programs obtain the information that they need to complete their task from four 
main sources: 

- from inside the program 

- from the user, for example when typing replies to prompts from the program 

- from the operating system 

- from disc files 

The last three classes are usually referred to as 'input' (because information is 'put' 
'in'to the program). Use of disc files is described separately later, because of its 
complexity - the other three sources will now be described in turn. 

Information from within the program 

Information that will be the same each time a program is run can be supplied as 
part of that program, in the form of constants. 

These can be used directly in instructions, for example: 

PRINT "***SUB-T0TALS***" 

Alternatively, they can be assigned to variables, which are then used as 
•pseudo-constants’ in the rest of the program, for example: 

title* = "***SUB-T0TALS***" 
etc 




PRINT titles 

6tC 

PRINT titleS;" finished" 

etc 

Using variables as pseudo-constants should save typing and make it easier to 
understand or change the program, particularly if the value is used several times in 
the program. 

You can also store constants in lists, using the keyword DATA. DATA is followed by 
one or more constants (numeric or string), separated by commas, for example: 

DATA 14,15,32,Apri1,666.21,-3,cabbages and kings 

DATA must be the last instruction on the program line. 

Note that double quotes (") are only necessary around a string item if it includes 
commas, leading spaces or trailing spaces. You may however prefer to use quotes 
all the time, to make sure. 

You may have any number of DATA statements throughout the program. It does not 
matter if they are positioned where BASIC 2 would attempt to execute them (they 
will just be skipped over). 

Information is read from DATA statements using the command READ, which is 
followed by one or more variables (separated by commas). For example: 

READ cats, dogs, owner_name$ 

READ reads information from DATA statements in order, starting with the first item 
in the first DATA line. Attempting to read past the last DATA item in the program, 
or attempting to read a string constant into a numeric variable will produce an error. 

READ and DATA are particularly useful when combined with a loop to initialise 
arrays of constants. For example, to set up an array called ‘days' with the number of 
days in each month (for a non-leap year): 

DIM days(1 TO 12) 

DATA 31,28,31,30,31,30,31,31,30,31,30,31 
FOR count = 1 TO 12 
READ days(count) 

NEXT 

Contrast this with assigning each value in turn: 

DIM days(1 TO 12) 

days(1)=31 

days(2)=28 

days(3)=31 

days(4)=30 

etc, up to 

days(12)=31 

READ normally reads each item in turn, advancing to the next DATA line when the 
last item in the present line has been read. The RESTORE command allows you to 
alter this. 

RESTORE on its own makes reading continue from the start of the first DATA line 
RESTORE followed by a location (line number or label), makes reading continue 
from the start of the first DATA line found, at or after that location. 
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If the location used with RESTORE does not exist, an error will result. 

RESTORE is often used to re-read DATA items, rather than store them in an array. 
This saves memory, at the expense of speed. For example, the previous example 
could be used to give the number of days in a month by adding the following onto 
its end: 

LABEL getday 

INPUT "Month number (1-12)";month 

PRINT "There are ";days(month);" days in month ";month 
GOTO getday 

To avoid using an array, you could use: 

DATA 31,28,31,30,31,30,31,31,30,31,30,31 
LABEL restart 

INPUT "Month number (1-12)";month 
RESTORE 

FOR count = 1 TO month 
READ days 
NEXT 

PRINT "There are";days;"days in that month" 

GOTO restart 

Information from the user 

One of the commonest ways to make a program versatile is to design it to use 
information supplied by the user when it is run. This information will usually be text, 
typed on the keyboard, or positional information from operation of the mouse. 

Keyboard input 

There are two main keyboard input facilities, provided by INPUT and INKEYS. 

INPUT is a command used to input numbers or text to variables, including array 
elements. It is followed by one or more variables, separated by commas, for 
example: 

INPUT input-variable(,input-variable...] 

When executed, INPUT displays a questio n mark to prompt the user to type 
something. When the user presses l <-* L the reply will be assigned to the 
input-variables. 

The text is interpreted as a list of items of information, for assigning to each 
input-variable in turn. This interpretation depends on the type of the input-variable, 
as follows. 

(If the type or number of items does not match the list of input-variables, an Alert 
Box will be displayed. Once you have clicked on the re try option, you will be 
returned to the reply you typed, to correct it using I <o«) I and retyping.) 

If the input-variable is a numeric variable, spaces are skipped, up to the start of the 
number, which is then assigned to the variable. The number may be a decimal, 
binary (ficXn) or hexadecimal (&n) constant. The end of the number is end of line or 
comma. 

If the input-variable is a string variable, spaces are skipped over until the first 
non-space character. If this is a double quote character ("), the text is read as a 



'quoted string' and all characters up to the next double quote or end of the line (ie 
I <-i | character) are assigned to the string variable. If this is not a double quote, all 
characters up to a comma or end of the line are assigned, dropping any trailing 
spaces. 

All this means that, to input sequences of numeric variables, the user should type 
numbers separated by commas. To input sequences of strings, the user should type 
the strings separated by commas and not use double quotes. If the user wants to 
include commas or leading or trailing spaces in an item, they should start and end 
the item with double quotes. 

You may also include text to be displayed as a prompt, immediately after INPUT: 

INPUT prompt ; input-variable],input-variable...] 
or INPUT prompt,input-variable[,input-variable...] 

prompt must be a string constant or the keyword PROMPT followed by a string 
expression or a string variable. If this is followed by a semicolon, it will be followed 
by a question mark when printed. If followed by a comma, no question mark will be 
added. 

When the user presses | <-■ | , the text cursor usually advances to the start of the 
next line. To suppress this, so that the cursor remains at the end of the teu the user 
types, put a semicolon at the end of the statement. For example: 

INPUT "Point co-ordinates, x and y";pointx,pointy; 

Finally, the text typed and any prompt are usually displayed in the output window 
(Results-1). To specify a particular window, include its stream number immediately 
after the INPUT command. For example: 

INPUT #2, "Point co-ordinates, x and y";pointx,pointy 

(The stream does not even have to be a screen window. For example, by specifying 
a stream which is open for input from a disc file (see OPEN), you can take input 
from that file (any prompts will simply be discarded).) 

To save a user having to put double quotes around strings that include commas, use 
LINE INPUT. This inputs the complete typed line to a single string variable. It is 
otherwise identical to INPUT. For example, to input any string and suppress the 
I jg I and question mark: 

LINE INPUT "Type anything you Like",reply$; 

There are three input functions used to get text from the keyboard: INPUTS. INKEYS 
and INKEY. 

INPUTS is used to get a fixed-length string from the keyboard. INPUTS does not 
display the characters typed and will accept any characters. Its single argument is 
the length of string required: 

string-variable = INPUTS (.string-length) 

Note that the user does not have to type I <-■ | to en d the s tring (indeed, it would 
be included in the reply, if typed!) and that keys like P<oin will simply type their 
character in the reply. 

INKEYS returns a single character from the keyboard, which is the first key pressed 
that has not been input in any other way. If there is no such key, it returns a null 
string. Note that unlike INPUT, INKEYS does not display any character typed, nor 
does it wait for keys to be pressed. 
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INKEYS is usually used within a loop (see REPEAT, WHILE, FOR), but can be 
demonstrated using GOTO: 

LABEL getkey 
a$=INKEY$ 

PRINT a$; 

GOTO getkey 

If a 'normal' key such as a letter or number is being pressed, the corresponding 
character will be returned. If a 'special' key such as a function key is being pressed, 
the string returned will normally be null, unless you have set up translation of key 
codes using OPTION INKEYS, in which case, the character returned depends on the 
key’s code and the translation string. (See OPTION INKEYS.) 

INKEY is very similar to INKEYS, but returns a numeric result: of -1 if no key has 
been pressed, otherwise the key's code. Values 0 - 255 are for normal characters, 
while 256 - 511 are for the 'special' keys, consisting of the key code plus 256. (See 
the appendices.) 

Mouse input 

The main user input device other than the keyboard is the mouse, which can be 
used to point to positions on the display, or 'clicked'. It can also be read indirectly, 
by moving the cursor and reading its position. 

To read the current mouse pointer position, use the functions XMOUSE and 
YMOUSE: 

result = XMOUSE 
result = YMOUSE 

result is an integer giving the X or Y position of the mouse pointer, in screen 
co-ordinates. 

To read the mouse buttons, use the function BUTTON: 
result = BUTTON f( button) ] 

button is an integer in the range 1 - 16, that specifies which button to read, 
numbering the leftmost button as 1, the next as 2, and so on (depending on the 
number of buttons on the mouse). If no argument is specified, the leftmost button is 
read. 

result is an integer in the range -1 to +15. -1 means that the button is not being 
pressed. Other results indicate that the button is being pressed and whether keys 
are being pressed with it. Each bit of the result indicates the state of a different key, 
as follows: 

Bit Significance 

0 righthan d I suw I 

1 lefthand I «mi I 

2 
3 


For exam ple, a result of 5 (&X0101) indicates that the mouse button, rctn I and 
righthand I «*» I are all being pressed. 









To read the cursor position, use POS, VPOS, XPOS or YPOS. 

For further details, refer to the chapters on text and graphics output. 

Information from the operating system 

A fourth, but rather minor source of information is the computer’s operating system. 

Keywords in this group provide information about: 

- discs and disc files 

- the computer’s clock 

- other devices 

Discs 

Getting information about discs is described in a later chapter. The types of 
information available include lists of files (displayed on the screen) and names of 
individual files that meet a specification. 

Time and date 

The second kind of information is provided by the functions TIME and DATE, which 
read the time and date from the computer's clock/calendar. _ 

TIME produces a number which is the time in hundredths of a second since 
midnight. It has no arguments. The result may be integer or fractional, depending | 

on the resolution of your computer's clock - see your computer user guide for j 

details. < 

Note that on some computers the clock's resolution is not as good as a hundredth of 
a second, or not an integer multiple of a hundredth. ( 

DATE produces an integer which is the date, in days since 31st December 1899 (1 
= Monday 1st January 1900). Without arguments, DATE gives the current date, 
with an argument DATE(sfnng) gives the specified date string as the number of 
days since 31st December 1899. 

A function DATES produces a string, giving the date in the conventional form (eg 
21/03/86). Without arguments, DATES gives the current date, with an argument 
DATE$(/nfeger) gives the specified number of days since 31st December 1899 as a 
date string. 

The format used to represent the date can be adjusted using OPTION DATE. 

Other devices 

You can read the configuration of various devices attached to your computer using 
functions such as XDEVICE and YDEVICE, which tell you the resolution of a 
graphics output device, in pixels. These functions are described in subsequent 
chapters, where appropriate. 
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3. WORKING WITH NUMBERS 
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This chapter describes how to perform calculations, using numerical information 
(numbers and numeric variables). You should already be familiar with numbers and 
numeric variables from the previous chapter on information, so that area will not be 
described again here. 

A calculation is carried out when an instruction is obeyed that contains the 
specification of the calculation required. This specification is called a 'numeric 
expression'. You can use a numeric expression almost anywhere that the equivalent 
number (numeric constant) would be allowed. 

The facilities will be considered in two main areas: 


- operators and expressions 

- functions 


Operators are the 'foot soldiers’ of numeric processing, used to combine numbers, 
variables and functions to produce expressions. An expression specifies the 
calculation that you want, in a form that BASIC 2 can understand. Example 
operators are plus (+) and minus (-); an example expression is '2+3-4'. 



Functions provide 'pre-packaged solutions’ for common calculations. For example, 
generating the logarithm of a number, or finding the lowest of a group of numbers. 


A numeric function is strictly defined as any function that yields a numeric result, 
but this chapter is limited mainly to those functions that are used for processing 
information. Other functions, used for input, output, discs etc are described in the 
chapters covering those topics rather than here, so that you can see them in 


context. 


This chapter will make more sense if you are already familiar with simple algebra, 
’equations’, or formulating solutions to problems like 'If it takes three men six days 
to dig a four foot trench, how long will it take two men to dig an eight foot trench?'. 
If this is not the case, you may need to read a book on programming or 
problem-solving to get the best out of the facilities described here. 


Operators and expressions 

A numeric expression consists of a combination of numeric operators and numeric 
items (constants/variables/functions), also known as 'operands’. It is evaluated to 
yield a single numeric result, when the instruction containing it is obeyed. 

The numeric items and operators in an expression alternate strictly in sequence: 
numeric [operator numeric...] 

Operators and operands should be separated by spaces to aid legibility (although 
this is not obligatory). 

There are two main types of numeric operator: ‘arithmetic operators', which are the 
ones used for everyday calculations and 'logical (or binary) operators', which are 
mainly used for expressing logical relationships but can also be used for 
manipulating individual bits of numeric values. 
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The result of the expression is automatically converted to the format required by its 
destination (eg to the range 0 - 255, if being assigned to a UBYTE field). If the 
result exceeds the permitted range for the destination, an error will result. Also see 
'Converting numeric values', below. 

Arithmetic operators 

The arithmetic operators, used for programming arithmetic calculations, are as 
follows: 

+ plus 

- minus 

* multiply 

/ divide 

\ integer division 
MOD remainder of integer division 
“ raise to a power 

The first four operators should need little explanation, except that you should note 
that in division the numeric being divided is to the left of the division symbol (/) 
while the numeric being used to divide comes after it. Typical expressions using 
these: 

cost * vat_rate 

totall + total2 + total3 

balance — payments + receipts + interest 

If an expression attempts to divide by zero, an error message is displayed but the 
program will carry on. The result of this division will be a signed infinity. BASIC 2 
will continue to operate on infinities, using slightly special infinity arithmetic rules. 
Infinities are printed as +1E99 or -1E99. 

The expression is completely evaluated before using the result, so that an 
instruction such as: 

cost = cost * 2 

will not cause any problems (this example simply doubles the previous value of 
cost). 

An expression may also start with either + or -, as ‘unary operators’. Unary + has 
no effect on the result, but unary - reverses the sign of the result. (The unary 
operators can also precede any operand.) 

The integer division operator \ rounds divisor and dividend to integer (see CINT), 
performs the division, then truncates the result to integer (see TRUNC) ie: 

x\y is the same as TRUNC(CINT(x)/(CINT(y)) 

The MOD operator rounds divisor and dividend to integer (see CINT) and yields the 
remainder resulting horn their division. Thus: 

7.1 NOD 3.3 
is evaluated as 
7 MOD 3 



\ 

x MOD y is the same as CINT(x) - ((rt\y)*CINT(y)) 

For example, to convert the time as returned by the function TIME (in hundredths of 
a second since midnight) into hours, minutes and seconds: 

total-seconds = CINTCTIME/100) 
hours = total-seconds\3600 
minutes = (total-seconds MOD 3600)\60 
seconds = total-seconds MOD 60 

v 

Finally, the exponentiation operator ", raises the value to its left to the power of the 
value to its right. For example: 

2 ~ 4 

is the same as 

2 * 2 * 2 * 2 

\ 

Note that the power used with * may be a fraction or negative. For example: 

2 * 0.5 

produces the square root of 2, while 
2 “ -4 
produces 

1/(2 * 2 * 2 * 2 ) 

Order of evaluation 

As described above, an expression is evaluated in stages. But which stages, in 
which order? This is exactly defined by rules known as 'operator precedence'. 

Operators are classified into groups according to their precedence. The parts of the 
expression including operators in the highest precedence group are evaluated first, 
from left to right of the expression. These intermediate results are then effectively 
substituted back into the expression and the parts with operators with the next 
highest precedence are evaluated, etc. 


Precedence group 

1 (highest) 

2 

3 

4 (lowest) 

For example: 
4*3-5 “2 + 3 

I I 

group 4 group 4 
group 3 group 1 


Operators 

unary+, unary- 

* / \ MOD 
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As * has the highest precedence, 5 ' 2 is evaluated first, producing: 

A * 3 - 25 + 3 

Next comes *, so 4 * 3 is evaluated next, producing: 

12-25 + 3 

As + and - have the same precedence, their parts are evaluated left to right, 
producing: 

-13 + 3 

Then: 

-10 

So the result is -10. 

If you are unsure of operator precedence or want to force a different order, use 
brackets to break the expression up into sub-expressions. The inside of each bracket 
will then be evaluated independently to yield a result which will be used in the rest 
of the expression. For example: 

A* (3-5) “2 + 3 

will be evaluated as: 

A * (-2) “2 + 3 

Brackets can be nested, in which case the innermost level is evaluated first, working 
outwards. For example, to calculate the final sum if interest is compounded 
annually: 

principle*((1+rate) “ years) 

Binary (logical) and relational operators 

You will probably use operators in this group mainly to express complex logical 
relationships in control structures (for details, see the chapter on control), but they 
can also be used to yield integer values, as follows. 

The integer values -1 and 0 are used to represent true and false respectively. In 
binary -1 is all Is and 0 is all Os. So you can think of the binary operators as 
working on true and false, with for example NOT TRUE being FALSE and TRUE 
AND FALSE being FALSE etc, or you can think of them as acting on the values true 
and false represent. 

All the binary (logical) operators round the values they are to operate on to integer 
first (see CINT). If this fails, an enor is generated. 

NOT is a unary operator that inverts each bit in the following value, for example. 
NOT 1 is 0. NOT 0 is 1. 

The other operators all operate on two values, immediately preceding and following 
them. They are as follows. 

AND sets bits to 1 in the result only if they were 1 in both values. 

OR sets bits to 1 in the result if they were 1 in either or both values. 

XOR sets bits to 1 in the result if they were 1 in only one of the values. 

The following ‘truth table' summarises their action. 






Operator 0 op 0 0 op 1 1 op 0 1 op 1 

AND 0 0 0 1 

OR 0 111 

XOR 0110 

The bitwise operators have the following operator precedence: 

(highest precedence) 

AND 

OR 

XOR 

(lowest precedence) 

The bitwise operators have a lower precedence than arithmetic operators. 
The relational operators are: 


< 

<= or =< 

>= or => 
> 

<> 


less than 

less than or equal to 
equal to 

greater than or equal to 
greater than 
not equal to 


They are used in relational expressions, yielding a result of 0 (false) or -1 (true). 

Relational operators have a precedence less than the arithmetic operators and 
greater than the bitwise operators. 

Numeric functions 

The functions described here all return a single numeric result, derived from one or 
more values (numeric or string constants, variables or expressions) supplied in 
brackets after the name. Most have a single argument, so they are used thus: 

name( argument ) 

A numeric function can be used almost anywhere that a numeric value is needed, 
for example to assign to a numeric variable, in an output instruction, numeric 
expressions or as an argument for another function. 

This section contains functions that are primarily concerned with processing 
information: functions that support input, output and disc use are described 
elsewhere, in the appropriate chapter. 

The functions described here deal with: 

- angles and trigonometry 

- logarithms and powers 

- maxima and minima 

- random numbers 

- signs 

- converting numeric values 

- converting text to numbers 

Many of these will be familiar if you have used a 'scientific 1 calculator, although of 
course BASIC 2 evaluates them much faster. (You can even add your own numeric 
functions to a program.) 


1U 


WORKING 
WITH NUMBFRS 



Angles and trigonometry 

BASIC 2 normally works with angles expressed as radians (but see OPTION 
DEGREES). 

To convert degrees to radians, use the function RAD: 

theta2 = RAD(theta) 

To convert radians to degrees, use the function DEG: 

theta = DEG(theta2) 

There are three trigonometric functions, for converting angles into cosines, sines and 
tangents: COS, SIN and TAN. Each takes a single numeric argument, in brackets. 
For example: 

opposite = adjacent*TAN<theta) 

There are also three functions to convert cosines, sines and tangents back into 
angles: ACOS, ASIN, ATAN. For example: 

theta.= ATAN(opposite/adjacent) 

(ATAN can also be spelled ATN.) 

There is also a function provided to simplify tasks like converting cartesian 
co-ordinates to polar co-ordinates: ATAN2. This takes two arguments: 

angle = ATAN2(x,y) 

Where x and y are the co-ordinates. The angle returned is in the range -it to +ir 
radians (-180 to +180 degrees), correctly interpreting negative arguments and 
coping with an x value of zero. With x and y both zero, ATAN2 returns zero. 

Finally, there is the 'pseudo-constant', PI, which returns the value of it. 

Logarithms and powers 

As described previously, to raise a number to a power, use the exponentiation 
operator, *. For example, to print 7 to the 4.4th power: 

PRINT 7 * 4.4 

To find the nth root of a numeric value, make use of the fact that it this is the l/nth 
power of that value. For example, to find the cubic root of ‘y’: 

root3 = y"(1/3) 

To find the square root of a numeric value, use the function SQR. This takes a single 
argument, which must be positive. For example: 

a = SQR(b"2 + c"2) 

There are two logarithmic functions. To calculate the natural logarithm of n, use 
LOG(n). To calculate the logarithm to base 10 of n, use LOGlO(n). n must be 
positive. 

To raise 'e' to the power n, use EXP(n). This can be used as an antilogarithm 
function for natural logarithms, n should be in the range -88 to +88. More negative 
arguments yield 0, more positive arguments cause overflow, yielding an error. 

(The antilogarithm of a base 10 logarithm is, of course. 10'n.) 
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Maxima and minima 

To pick out the highest value from a list, use MAX. This takes a variable number of 
numeric arguments and returns the highest value. For example: 

PRINT "The winning score is MAXtmarktD/marktZi/inarkGJ^marktA)) 

Highest is taken to mean 'most positive', so that if the arguments are negative, 

MAX returns the least negative one. 

Similarly, to pick out the lowest (most negative) number from a list, use MIN. 

Random numbers 

Random numbers are obtained using the function RND, as follows. 

RND without an argument (RND) returns a decimal fraction 'n‘ which is in the range 
0 < = n <1. 

RND with a positive argument rounds that argument to an integer 7 (see CINT), 
then returns an integer 'n' in the range 1 <= n <= /. 

BASIC 2 generates 'pseudo-random' numbers - numbers in a sequence where each 
depends completely on the previous number. Starting from a given value, this 
sequence is always the same. 

To restart the sequence, use the command RANDOMIZE. This sets a new initial or 
'seed' for the sequence If followed by a numeric value (of any form and range), it 
uses this value. For example: 

RANDOMIZE TIME 

Where TIME is a function with the number of hundredths of a second since 
midnight as its value. 

If used without a parameter, BASIC 2 assumes RANDOMIZE TIME. 

By specifying the same seed, you can ensure that exactly the same sequence of 
random numbers will be generated. This is particularly useful when testing 
programs. 

Signs 

To ensure that a numeric value is positive, use ABS. This converts a negative or 
positive number to a positive number of exactly the same magnitude: 

ABS (.value) 

To determine the sign of a number (expression, variable), use SGN. This returns 0 if 
the value is 0, -1 if it is negative, +1 if it is positive. This provides a convenient 
way of 'compressing' the range of a value. For example: 

DIM state$<—1 TO 1), productS(IM), stock(KW) 

state$<—1) = "overdrawn" 
state$<0> = "nil stock" 
state$(1) = "in stock" 

state = SGN(stock(item)) 

PRINT product$(item);" is ";state$(state) 

lit 
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Converting numeric values 

When a numeric value is used, it is usually automatically converted to suit that use. 
This mainly consists of rounding fractional values to integer, for example, when used 
as an argument for a function that takes integer arguments. 

While you ought to be aware of this conversion, you need not do anything to 
produce it. It is carried out as follows: 

When rounding to integer, the value is rounded at the first decimal place. Rounding 
is up or down; digits 0-4 round down, and 5-9 round up. For example, if 
assigning to an integer array element: 

4.0 to 4.4 round to 4 

4.5 to 4.9 round to 5 

If the magnitude of the value is outside that allowed for the destination, an error will 
result. 

There are also functions to convert a numeric value to integer explicitly. These are 
used to force a conversion where one would not normally take place, or to produce 
a conversion other than that which would occur. 

These functions are FLOOR, CEILING, CINT, TRUNC and ROUND. 

To round a number to the next smaller (more negative) whole number, use FLOOR. 
FLOOR(3.9) will produce 3. while FLOOR(-3.9) will produce -4. (An alternative 
name for FLOOR is INT.) 

To round a number to the next larger (more positive) whole number, use CEILING. 
CEILING(3.9) will produce 4, while CEHJNG(-3.9) will produce -3. 

The result produced by CEILING and FLOOR will be the same as the argument if 
the argument has no fractional part. 

To round to an integer in the range -2,147,483,648 to +2,147,483,647, use CINT. 
CINT is the same as ROUND, except that an error will result if the number is 
outside this range. 

J To round a number by simply losing the fractional part, use TRUNC. TRUNC(3.9) 

• will produce 3, while TRUNC(-3.9) will produce -3. 

To round a number to a given number of places, use ROUND(number,p/aces). 
ROUND(3.335,2) would produce 3.34 while ROUND(-3.335,2) would produce -3.34. 
If omitted, places is taken as 0, so ROUND(3.335) produces 3. 

If places is negative, it is taken as the number of figures to round to on the left of 
the decimal place; for example, ROUND(12345.67,-3) will produce 12300. 

Finally, to determine the fractional part of a number, use the function FRAC. For 
example: 

c = FRAC(n) 

FRAC(n) is equivalent to n-TRUNC(n) 
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Converting text to numbers 

Strings (text) are stored in a quite different way to numeric information, but can be 
converted to a numeric form for use in calculations, by using the functions ASC and 
VAL. 

ASC returns the code of the first character in its string argument. For example: 
PRINT ASCC'ABCD") 

would print 64, because that is the character code for “A”. If the argument is a null 
string, ASC will produce an error. 

To convert a string version of a number to a number, use VAL, for example: 
number = VAL(numberS) 

VAL starts conversion at the first character of its argument, exactly as described for 
INPUT. This string can thus include binary (&Xn) and hexadecimal (&n) strings, 
leading and trailing spaces. 

For example: 

PRINT VAL<" &FF ") 

255 

(There are a range of string functions which convert numeric arguments to strings: 
CHR$, STR$, DECS, BINS, HEXS - see the next chapter.) 
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4. WORKING WITH TEXT 


This chapter describes the facilities provided for manipulating text information 
(string constants and variables), under the following main headings: 

- string operators and expressions 

- string functions and substrings 

String operators and expressions 

There is only one string operator, This adds the string to its right onto the end 
of the string to its left. Note that this is quite different to the action of in a 
numeric expression. 

Thus, a string expression is: 

string [+string...] 

where string is a string constant or variable, as described previously. 

Operator precedence in string expressions is thus very simple, with evaluation 
proceeding strictly from left to right. You cannot use brackets to change this order of 
evaluation. 

Assigning to string variables has already been described, in the chapter on 
information and input. 

String lunctions and substrings 

The string functions provided are classified into the following classes: 

- splitting strings 

- examining strings 

- generating strings 

- converting strings 

- converting numbers to strings 

Splitting strings 

The simplest way to extract text from within a string is by using substrings. A 
substring specifies what part of the preceding string variable or expression to return, 
as follows: 

string {.start TO end} 

- extracts a substring starting at start and finishing with end. 
string {.start} 

- extracts a substring consisting of the single character at start 
string {.start T0> 

- extracts a substring from start to the end of the string variable 
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string -CTO end> 

- extracts a substring from the beginning of the string variable to end 

The positions start and end can be positive or negative. If positive, they refer to the 
nth character from the start of the string (first character = 1); if negative, they refer 
to the nth character from the end of the string. Thus, to extract characters from the 
3rd to last but one character: 

string { 3 TO -2> 

start and end may be the same giving a single character substring. If end is before 
start this gives a null substring. 

There are also three functions that extract text from within a string: LEFTS. MID$ 
and RIGHTS. (These are mainly provided for compatibility with earlier versions of 
BASIC, as the equivalent effects can be achieved more easily using substrings.) 

To extract the first length characters from a string, use: 

LE FTS ( string-expression, length) 

(this is equivalent to the substring specification <10 lengthy) 

To extract the last length characters from a string, use: 

RIGHTS ( string-expression , length ) 

(this is equivalent to the substring specification <— length T0>) 

To extract length characters starting from start in a string, use: 

HI DS ( string-expression, start, length ) 

(this is equivalent to the substring specification { start TO start+length—\y) 

To extract all the remaining characters from start to the end of a string, use: 

HIDS ( string-expression, start ) 

(this is equivalent to the substring specification {.start TO >) 

Generating strings 

To produce a string of length characters, all with the character code numeric, use: 
STRINGS < length, numeric) 

To produce a string of length characters consisting of the first character of string 
expression, use: 

STRINGS( /engfh, string-expression) 

For example, the command: 

PRINT STRINGS(20/'*");"Hi!";STRINGS<20,42> 

Would produce: 

because the character code for is 42. 

(There are other functions, used to generate strings from numbers, as described 
below.) 



Examining strings 

Strings can be compared in relational expressions just like numeric values (see 
relational expressions). 

There are also two functions that help you to examine strings, by returning the 
length of a string and locating any occurrences of another string within it. 

To find the length of a string, use LEN, which returns the length of its string 
argument: 

LEN ( string-expression) 

For example: 

chars = LEN(title$+name$) 

This is particularly useful when you need to process the string a character at a time, 
such as in the following routine, which displays the string in titles double-spaced 
across the screen: 

characters = LEN(titleS) 

FOR a = 1 TO characters 
PRINT title$<a>+" 

NEXT 
PRINT 

To check whether a string contains another string, use INSTR. This takes the form: 
lUSJRi [start, ]string-expression-1, string-expression-2) 

start is a numeric expression that specifies where in string-expression-1 to start 
searching for string-expression-2. If start is omitted or 1, the string will be searched 
from its beginning. 

INSTR returns a numeric result, which is 0 if string-expression-2 could not be found 
when searching from the given start. If the result is not 0, it is the position in 
string-expression-1 of the start of string-expression-2. 

For example, to count the number of occurrences of the string 'lookforS' in the 
string 'sentences': 

lookfrom = 1 
found = 0 
LABEL again 

lookfrom = INSTR<lookfrom,sentence$,lookforS) 

IF lookfrom <> 0 THEN found=found+1:lookfrom=lookfrom+1:GOTO again 

Converting strings 

Text strings can include a wide variety of characters, including capitals (upper case) 
and small (lower case) letters. There are two functions to convert letters from upper 
to lower case and vice versa. 

To convert a string expression to upper case, use: 

UPPERS ( string-expression) 

To convert a string expression to all lower case (ie small letters), use: 

LOWERS ( string-expression) 
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Note that this conversion does not affect any symbols other than the letters ’a’ - 'z' 
and ‘A’ - 'Z\ and the accented letters. If there is no capital version of an accented 
character, it will be converted to the equivalent unaccented capital character. 

Converting numbers to strings 

The function CHR$ returns the character for a given character code, as a single 
character string: 

CHRS(code) 

This function can thus be used to 'type' any of the 256 available characters. 

Numeric values cannot be used as strings, nor can strings be used as numeric 
values, but functions are provided to convert numeric strings to numeric values and 
vice versa. 

To convert a number to exactly the same representation as would be used to print 
it. use STR$: 

STR$ ( numeric-expression) 

To convert a numeric expression to the equivalent hexadecimal stnng, use HEX$: 
HEX$ ( numeric-expression) 

To convert a numeric expression to the equivalent binary string, use BINS: 

BINS ( numeric-expression) 

To convert a numeric expression to a formatted decimal string, use DECS: 

DECS ( numeric-expression, format-template) 

The format-template is a string-expression that dictates how the number will be 
formatted, using a subset of the facilities of a PRINT USING template. It does so 
using the characters +—$*#, . and “, as follows. Note that the string 
produced will usually be the same length as the template. 

Each ft in the template specifies a digit position. If there is no ., only the integer 
part of the number will be output, with no decimal point. If there is a ., a decimal 
point will be output at this position. The number is rounded to the number of places 
output. 

A , anywhere to the left of the . (if present) specifies that digits to the left of the 
decimal point will be grouped into threes, separated by commas. (But see OPTION 
for continental alternatives to dot and comma.) 

Thus, to format the string to 4 digits and no decimals, the template would be: 

"ft HUM " 

To produce 9 digits, grouped into threes, with 2 decimal places: 

" UUU,UU»,»MH.»ir 

If the numeric expression being converted is too small to fill the template, leading 
places will be filled with spaces. If it is too large, the result will have as many 
leading digits as necessary. 

Positive numbers will normally be printed without a sign, negative numbers with a 
leading negative sign (which occupies one of the digit positions specified by a # or 
the position specified by a leading -). 



To specify that the minus sign be output at the end of the string for negative 
numbers, place a at the end of the template. To specify that a '+' sign be 
output for positive numbers, place it either at the start or end of the template; plus 
and minus signs will then both be output at this position. 

To specify that instead of leading spaces, leading asterisks should be output, place 
** at the start of the template (but after any leading sign). This also specifies two 
further digit positions. To specify that the number should start with a $ sign, put $$ 
at the start of the template (but after any leading sign). This specifies an extra digit 
position. To specify both leading asterisks and a leading $. place **$ at the start of 
the template (but after any leading sign) - this also specifies an extra 2 digit 
positions. (You can also specify other characters for currency symbols: see OPTION 
CURRENCY.) 

Thus, to produce strings with leading asterisks instead of spaces. 6 digits and a 
trailing minus sign, the template would be: 

To specify 9 digits in groups of three, 3 decimal places, leading asterisks, $ and 
either a + or a - sign: 

"+**$# ,m ,#uu .###" 

Finally, you can specify that the number be output using an exponent, by adding 

-to the end of the template before any trailing sign, or * which has a 

similar effect, but produces an exponent that is a multiple of 3 (as used in 
engineering). 


; 
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5. TEXT AND GRAPHICS OUTPUT 


Text output consists of letters, numbers, punctuation marks, mathematical symbols, 
etc, usually combined to produce sensible, legible text such as English sentences or 
tables of figures. The information that is output as text can be derived from numeric 
or string constants, variables or expressions (as described in previous chapters). 

Graphics output consists of dots, straight lines, curves, patterns etc. usually 
combined to produce pictures such as pie charts, engineering drawings, 
self-portraits, etc. 

This chapter describes the facilities provided for general-purpose text output. Many 
other facilities display or print text as part of their role, such as the disc command 
DIR, which lists file names, or selecting a menu with the mouse, which displays the 
menu options. These are described elsewhere, where appropriate to their main role. 

This chapter also describes how to output graphics to a display. You can also use 
most of the facilities described here with other graphics devices, as described in the 
next chapter. 

Text and graphics can be output to two main destinations: a display or a printer. 
Text can also be output to a disc file. 

Output to the display is very fast and well-endowed with facilities. Output to a 
printer is rather slower and less versatile, mainly due to limitations of printer 
technology, but has the advantage that the output is preserved (on paper) in an 
easily portable form. Output to a disc is invisible and only really used to store 
information for later re-use. 

All output is normally displayed in the Results-1 window, but it can easily be routed 
instead to other destinations, by adding an optional parameter (its stream number) 
to the output command. This makes it easier to develop and test programs, for 
example by routing output intended for a disc to the display, so you can check it 
easily. 

This chapter is divided into the following sections: 

- simple text output 

- virtual screens and windows 

- text output to a graphics screen 

- text output to a text screen 

- text output to a printer 

- graphics output 

(Disc output is described in Chapter 8 of Part m and Chapters 1 and 2 of Part IV.) 

If you have not got a suitable printer connected to your computer, you will of course 
not be able to use the printing facilities described. 
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Simple text output 

Text output to the display consists of characters from the GEM text character set. 
described in Appendix I. You will probably mainly use characters with codes in the 
range 32 - 127, as these include all the (unaccented) European letters, numbers, 
punctuation marks and common symbols. 

BASIC 2 gives you considerable flexibility in the way in which text is displayed, 
including its position, exact layout and character style. This enables you to produce 
attractive, informative results, making the most of the power and versatility of the 
GEM environment. 

Your display is divided up into a number of separate 'windows' which you can use 
rather like separate (smaller) displays. When text is output to a window, it is stored 
and formatted as if written to a larger area, called a ‘virtual screen’ - the window 
simply gives you a view of part of this virtual screen. 

You can move BASIC 2’s windows around the display, enlarge, shrink, or scroll 
them (across the virtual screen) by using your mouse, just like other GEM windows. 
You can also manipulate windows and virtual screens using BASIC 2 commands 
and functions. However, for this simple description of text output, we will ignore 
virtual screens, windows and their many facilities, and pretend that text is simply 
output direct to a single display area, called a 'screen'. 

For text output, the screen can be considered as if divided into a number of cells, 
each of which is large enough to contain a single character: 


Columns 



Positions within the screen can be referred to by their column and line number, with 
the top left comer of the screen being column 1, line 1. 

Each time a character is displayed, a pointer called a 'cursor' advances to the next 
cell across the screen. This indicates where the next character will be placed, by 
default. The cursor usually advances to the start of the next line when it tries to go 
past the righthand side of the screen. 

If the cursor attempts to move beyond the bottom of the screen, the screen contents 
will normally move up a line (scroll) to keep the cursor visible. This loses the top line 
of the display. 
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Text output commands 

The simplest output command is CLS, which clears the screen and moves the cursor 
to its top left corner. 

Text is displayed using the command PRINT, followed by the items to display. 
PRINT displays items as text, regardless of whether they are string or numeric, 
constants, variables or expressions, so you need only use conversion functions if the 
default format used to display an item is not suitable. 

PRINT in general displays text in ‘free format', as follows. Strings are displayed 
exactly as given, while numeric items are displayed using the minimum number of 
characters necessary (eg. by removing trailing zeros), in decimal. Positive numbers 
are displayed with an initial space, negative numbers with an initial minus sign. 

Each item of text is normally displayed starting at the current cursor position, unless 
it is too long to fit on the line, when the cursor will move to the start of the next 
line first before printing it. 

The only general exception is when printing characters with codes less than 32 
(‘control codes') and 'escape sequences’. For example, character code 9 (TAB or 
Control-I) is printed as sufficient spaces to move the cursor to the next tab position 
across the screen. Tab positions are fixed at every eight characters across the 
screen. 

A PRINT instruction always starts with the keyword PRINT, which may be followed 
by items to print and items to control that printing, known as ‘print functions'. 

PRINT on its own simply moves the cursor to the beginning of the next line of the 
screen. 

PRINT can be followed by one or more items to display. If there is more than one. 
they must be separated by commas or semicolons. For example: 

PRINT "Total:";total+subtotal 

The items are printed in the same order as in the PRINT instruction. 

Unless the last character in a PRINT instruction is a semicolon, the cursor will move 
to the start of the next line after the PRINT instruction has been executed. A final 
semicolon makes the cursor remain after the last item displayed. Commas and 
semicolons also affect how the items in a list will be positioned when printed, as 
described next. 

Positioning 

Items in a PRINT instruction that are separated by semicolons are displayed 
immediately adjacent, without intervening spaces. 

An item preceded by a comma is displayed at the next 'print zone' on the screen. 
Print zones are positions every n cells across the screen; n is initially set to 18 when 
selecting BASIC 2, but their widths can be changed using the command SET 
ZONE: 

SET ZONE cells 

Separating items with commas therefore provides an easy way of tabulating items of 
similar lengths. (Note that print zones are not the same things as the tab positions 
used when printing Control-I.) 


Print zones can also be changed temporarily by using the print function ZONE(ce//s). 
This has the same effect as SET ZONE, but only on positioning of subsequent 
output in the PRINT instruction in which it is used. 

You can also move the cursor directly to control positioning of subsequently printed 
text. Note that this does not alter the contents of the screen, unless the movement 
causes it to scroll (see below). 

To move the cursor to a particular position on the screen, use the command 
LOCATE: 

LOCATE x;y 

This moves the cursor to column x, line y. The top left corner of the screen is 
defined as 1;1. 

You may also choose to omit one or both of these parameters: the current cursor 
position will then be used instead for the appropriate dimension. If you specify just a 
single parameter, it will be taken as the column unless you precede it by a 
semicolon, when it will be taken as the line. 

You can also position text within a PRINT instruction, by preceding it with the 'print 
functions' TAB(x) or AT(x;y). TAB(x) moves the cursor right to column x on the 
current line, or to column x on the next line if the cursor is already to the nght of 
column x. AT(x;y) moves the cursor to column x, line y. Both are printed as if 
followed by a semicolon. 

TAB without an argument is printed as the tab character (Control-1), moving the 
cursor to the next tab stop. 

To read the current position of the cursor, use the functions POS and VPOS: 

column = POS 
line = VPOS 

Positioning can also be controlled by printing control codes and escape sequences. 
(This allows you to. for example, embed positioning information in the string you 
want to print, rather than in the PRINT instruction.) 

Control codes are single characters with codes in the range 0-31, and code 127. 
The following are obeyed: 


Code 

Name 

Effect 

7 

BEL 

sound a bleep 

8 

BS 

move cursor left one column 

10 

LF 

move cursor down one line, scrolling if needed 

13 

CR 

move cursor to start of current line 

27 

ESC 

start escape sequence 

127 

DEL 

delete character 


Note: DEL will only correctly delete the character to the left of the cursor if it was 
printed using normal sized characters in the system font. 

(Control codes are normally obeyed or ignored, not displayed. However, if there are 
characters defined for these codes, you can display them by preceding the control 
code by an escape character ie. character code 27.) 



Escape sequences are sequences of characters that start with the 'ESC' character, 
code 27. 

The escape sequences used to control positioning are: 


Sequence 

ESC A 
ESC B 
ESC C 
ESC D 
ESC H 
ESC I 
ESC Y x y 
ESC j 
ESC k 


Effect 

move cursor up 1 line 

move cursor down 1 line 

move cursor forward 1 column 

move cursor backward 1 column 

move cursor to top left ('home') 

move cursor up 1 line, scrolling if necessary 

move cursor to column x-31, line y-31 

save cursor position 

move to saved cursor position 


For example, when the following string was printed, it would print ACCOUNTS at the 
top of the screen, then return to the current cursor position: 


save 

position 


+ esc$+"H" 

v -v-' 

home 

cursor 


+ 


"ACCOUNTS" + esc$+"k" 


move to 
saved position 


(where esc$ had previously been assigned the ESC code, using 'esc$ = CHR$(27)') 
ESC Y is equivalent to the AT print function (and similar to the LOCATE command). 


Displayed format 

Items in a PRINT instruction are normally displayed in 'free format' as described 
previously. To take control of the format, include the USING keyword in the PRINT 
instruction, as follows: 

PRINT [items] USING format-template} using-list [terminator] 
where terminator is a ; or , (as described previously). 

The format-template is a string, string variable or string expression that specifies 
how to format the items in the following using-list when they are displayed, items 
before the USING keyword are printed in free format. 

using-list consists of items to print, separated by commas or semicolons - these are 
treated as equivalent and only serve to separate items, not to control positioning. 
When formatted and printed, items will not be checked to see if they will fit onto 
the line, but simply printed consecutively, as dictated by the format-template. 

format-template consists of one or more templates, sometimes separated by 
non-template characters. Each template indicates how to format a single string or 
numeric item in using-list, as follows. The first item is formatted according to the 
first template, the second item according to the second template, and so on. If there 
are more items in using-list than templates, the format-template will be used again 
- with the next item in the list being formatted according to the first template, the 
one after that according to the second template, and so on. 




The forms these templates can take are described below. If the template type does 
not match the item type, an error will result. 

Any characters included in format-template between templates that are not 
template characters will be output in the corresponding position, unchanged. 

Formatting strings 

Strings are formatted with a string template, which must be one of: 

! print just the first character of the string 

\n-spaces\ print the first n+2 characters of the string 

& print the whole string 

For example, to print a table of names and scores: 

DATA Superman, 100, Ant, 1, AttiLa the Hun, 99 
FOR count = 1 TO 3 
READ persons, score 

PRINT "Score for ";USING "\ \ =";person$; 

PRINT score 
NEXT 

This would print: 

Score for Superman = 100 
Score for Ant = 1 

Score for Attila th = 99 

(In the last line, “Attila the Hun" has been truncated by the 9-character template.) 

If the string being output is shorter than the template specified using "\spaces\", it 
will be padded with spaces, on the right. 

Formatting numbers 

Numeric items are formatted with a numeric template. This is far more complex that 
a string template, consisting of a combination of the following characters: 

As long as the template is large enough, the text output will be the same length as 
the template, which greatly simplifies tasks like printing tables. 

Each # in the template specifies a digit position. If there is no ., only the integer 
part of the number will be output, with no decimal point. If there is a .. a decimal 
point will be output at this position in the field specified by the #s. The number will 
be rounded to the number of places output. 

A , anywhere to the left of the . (if present) specifies that digits to the left of the 
decimal point should be grouped into threes, separated by commas. (But see 
OPTION DECIMAL.) 



Thus, to display a number as 4 digits with no decimal point or decimal places, the 
template would be: 

I > // // // // ft 
ft ft ff ff 

For example: 

PRINT USING "####";12.345 

would display: 

12 

while 

PRINT USING "####";1234.5 

would display: 

1234 

To produce 9 digits, grouped into threes, with 2 decimal places: 

" u u-u - u u -u- j HHt 

ff ft fr f ft ft ft ftffrrr • ff rr 

For example: 

PRINT USING "###,###,###.##"; 12345.678 
would display: 

12,345.68 

If the numeric expression being printed is too small to fill the template, leading 
places will usually be filled with spaces (but see below). If it is too large, the output 
will consist of the whole integer part and the number of decimal places specified by 
the template. 

Thus, for example, a template of # will print any size number, rounded to integer, 
using the minimum number of digits. 

A positive number is normally printed without a sign, while a negative number will 
be printed with a minus sign immediately before the first digit. (The minus sign 
occupies one of the specified digit positions.) 

To control the placing and use of signs, put a + or - at the start or end of the 
template. A - specifies the position for a space (if positive) or minus sign (if 
negative). A + specifies the position for a plus sign (if positive), or minus sign (if 
negative). 

To specify that instead of leading spaces, leading asterisks should be output when 
the number being printed is smaller than the template, place ** at the start of the 
template (but after any leading sign). This also automatically specifies the first two 
digit positions at the beginning of the template. This form is often used when 
printing amounts of money (for example, on cheques). 

To specify that the printed number should start with a currency symbol such as £ or 
$. put $$ at the start of the template (but after any leading sign). This automatically 
also specifies the first digit position at the beginning of the template. If you have 
changed the currency symbol (see OPTION CURRENCY), still use $$ in the 
template: the new currency symbol will be printed instead of a $. If the currency 
symbol is more than one character, use an extra $ in the template for each 
additional character. For example, if the currency symbol is FFt. use $$$$ in the 
template. 




To specify leading asterisks and a currency symbol, place **$ at the start of the 
template (but after any leading sign) - this also specifies the first two cLgit positions. 
Again, use extra S symbols in the template if the currency symbol is more than one 
character. 

Thus, to print a number with leading asterisks, 6 digits and a trailing minus sign, 
the template would be: 

"» *#### » 

To specify 9 digits in groups of three, 3 decimal places, leading asterisks, $ and 
either a + or a - sign: 

H UH 

■ fit it it / it ft ft • ii it n 

Finally, you can specify that the number be printed using an exponent, by adding 
to the end of the template (before any trailing sign), or *, which outputs 
numbers with an exponent that is a multiple of 3 (engineering form). For example: 

PRINT USING "###.###“ ~~*";1.23E43 

would produce: 

12.300E+42 

As described previously, a format template can consist of templates for more than 
one item, so to tabulate the scores in the previous example properly, you could use: 

DATA Superman, 100, Ant, 1, Attila the Hun, 99 
FOR count = 1 TO 3 
READ person), score 

PRINT "Score for ";USING "\ \ = ###";person$,score 

NEXT 

This would print: 

Score for Superman = 100 
Score for Ant = 1 

Score for Attila th = 99 

Text style 

Text is normally printed as black, in the system font, but you can vary the style 
(thick, light, italic, etc.) and colour used, as follows. 

To change the colour of subsequent items in a print statement, include the print 
function COLOUR(colour-number ). For example: 

PRINT "You are ";C0L0UR(2);ABS<balance);C0L0UR<1);"overdraun" 

(The colours available depend on your computer. Refer to the other guides supplied 
with it for details.) 

To change the text style for subsequent items, include in your PRINT instruction the 
print function EFFECTS( effects-1 [,effects-2]) 


130 



The interpretation of effects depends on which bits are set. Bits 0 to 6 have the 
following significance: 


Bit 

Binary 

representation 

Effect 


0 

(&X0000001) 

thick 

thick 

1 

(&X0000010) 

light 

light 

2 

(&X0000100) 

italic 

italic 

3 

(&X0001000) 

underlined 

underlined 

6 

(&X1000000) 

reversed 

■ • L% 


Note that text can be displayed using any combination of these effects, although 
certain combinations will not be very attractive or legible! 

You will probably find that the easiest way to specify effects is by using binary 
constants. Thus, to specify italic, reversed, use 8X0000010 + 8X1000000 ie 

8X1000010 

If only one parameter is supplied, the text is printed using that style. If two 
parameters are supplied, bits set in the first specify which effects to turn on. while 
bits in the second specify which effects to turn off. For example, to turn on 
thickening (bit 0) and underlining (bit 3). and turn off reversing (bit 6). use: 

PRINT EFFECTS(8X1001,8X1000000);" part";part_no 

To change the colour or print effects used in all subsequent print instructions (ie. 
the default colour and print effects), use the command SET, followed by the 
appropriate print function(s), which this time don't have brackets around their 
parameters. For example, to set the colour to 1 and effects to light italic: 

SET COLOUR 1 EFFECTS 8X110 

Note the difference between print functions in PRINT commands, which change the 
style temporarily (for the rest of the PRINT command) and print functions in SET 
commands, which change the style used as a default in all subsequent PRINT 
commands. 

To restore the text style to its initial state and clear the screen, use: 

CLS RESET 

Text style can also be changed by printing escape sequences, as follows: 


Sequence 

ESC b c 
ESC m 
ESC n 
ESC p 
ESC q 
ESC r 
ESC u 
ESC s 
ESC t 
ESC x 
ESC y 


Effect 

set foreground colour 
enter lightened mode 
exit lightened mode 
enter reverse video mode 
exit reverse video mode 
enter thickened mode 
exit thickened mode 
enter underlined mode 
exit underlined mode 
enter italic mode 
exit italic mode 



Although these escape sequences appear to just duplicate the COLOUR and 
EFFECTS keywords, they can be used in other ways. For example, to set up the 
string variable ‘titleS’ so that it will be printed as underlined italic: 

esc$ = CHR$(27) 

titles = esc$+"s" + esc$+"x" + "LIST" + esc$+"t" 

--V-' '-V-' '- v -' 

underline italic - underline 

on on off 


■ esc$+"y" 


italic 

off 


Cursor behaviour 

The cursor is normally invisible, but can be made visible, using the command 
WINDOW CURSOR: 

WINDOW CURSOR ON 

(This has an effect on scrolling - see later.) To make it invisible again: 

WINDOW CURSOR OFF 

Usually, the cursor will move automatically to the start of the next line (wrap) when 
a character has been printed at the rightmost edge of the screen. To prevent this 
happening, use the SET command: 

SET WRAP OFF 

The cursor will now only move to the start of the next line when a carriage return 
and line feed are printed (ie. character codes 13 and 10). Note that a carriage return 
and line feed will be output first automatically, if the text to be printed would not fit 
onto the current line. 

To restore normal wrapping, use the command: 

SET WRAP ON 

Similar effects can be produced by printing escape sequences, as follows. 


Sequence 

ESC e 
ESC f 
ESC v 
ESC w 


Effect 

make cursor visible 
make cursor invisible 
wrap at line end 
no wrap at line ond 


Virtual screens , streams and windows 

As described earlier, when text and graphics are output to the display, they are 
stored and formatted to suit an invisible 'virtual screen', part of which is visible 
through the virtual screen's 'window’. 

There are two types of virtual screen: 'graphics screens' which can display text and 
graphics, and 'text screens' which can only display text. 

The description of simple text output given earlier in this chapter applies equally to 
either type of screen. The differences only become apparent when you examine the 
more sophisticated facilities they provide, as follows. 






A graphics screen: 

- has fewer 'editing' facilities 

- can hold less text 

- provides: a variety of text fonts 

a variety of text sizes 
angled text 
automatic indentation 

write modes (replacing or writing over text/graphics already on the screen) 
graphics 

A text screen: 

- is handled more quickly 

- can store more text 

- has more 'editing' facilities 

While a graphics screen allows you to produce more attractive displays, either type 
of screen will do for 'normal' text output, although text screens have the advantages 
of greater speed and text capacity. 

When you select BASIC 2, it sets up a virtual screen of each type for your exclusive 
use and two other text screens, which it uses (in Direct mode). You can use these 
two other screens for output or redefine how any of the four screens is set up. This 
is described in the next chapter. 

Streams 

Text (and graphics) commands usually output to the default stream, which is 
initially attached to the supplied graphics screen, called Results-1. You can however 
use up to four different screens, by specifying the number associated with the 
screen (its 'stream number') in the output command. 

The stream number is preceded by a '#’ in the output command and must be the 
first item after the command keyword. If the next item after the stream number is 
not a keyword, the stream number must be followed by a comma. 

For example, using PRINT: 

PRINT #stream, print-items 

PRINT #stream USING format-template; using-list 

stream is an integer expression (or constant or variable) in the range 0 - 15. You can 
use streams 0 to 2 without any preparation: 0 is the system printer. 1 and 2 are the 
graphics (Results-1) and text (Results-2) screens reserved for use by your programs. 
You must set up streams 3 to 15 before you can use them. It is simpler if you use 
streams 1 and 2 for now. (Details of using the other streams are given in the next 
chapter.) 

Stream numbers can be specified with all the commands previously described for 
simple text output ie. PRINT, LOCATE. SET, CLS, CLS RESET and WINDOW 
CURSOR. The functions POS(#sfream) and VPOS(#sfream) can also be used, to 
determine the cursor position within any screen, by specifying the stream attached 
to it. 



For example: 

PRINT #1, name*;" lives at ";address$ 

As another example, INPUT would normally display its prompt and the typed reply 
in the default output screen, but to prompt using a different screen, use: 

INPUT #stream, [prompt] input-variables 

For example: 

INPUT #main, "Type the name" / id$ 


Positions and units 


In the rest of this chapter, you will find positions and measurements given using 
two different systems: 

- lines and columns (text coordinates) - for positioning text on text and graphics 
screens 

- user coordinates - for positioning graphics (and text) on graphics screens 

Lines, and columns have been used throughout the first part of this chapter. 
Positions are specified as columns jines, giving the number of columns and lines 
(based on the standard system font) away from the top left corner of the virtual 
screen (1;1). 


4 mlnmn.c; 



text co-ordinates 


User coordinates are mainly used for positioning when using graphics. They are 
much finer than lines and columns. The actual dimensions of user coordinates 
depend on a number of factors (see USER SPACE). When a graphics screen is 
defined, its user coordinates are automatically set so that the shorter side is 5000 
user coordinates long. The longer side will be more than 5000 user coordinates long, 
because the same scale is used for both axes, so that squares will be square when 
displayed! Note: the area of Results-1 which you see displayed on the screen 
initially is approximately 5000 square. 

Positions are specified in user coordinates as horizontal:vertical , giving the number 
of honzontal and vertical user coordinates away from the 'user origin' (0;0), which is 
initially the bottom left corner of the virtual screen (but see USER ORIGIN). 







graphics screen 



user co-ordinates 

Windows and scrolling 

Each virtual screen has a window, which is shown on the display and reveals some 
or all of the contents of the virtual screen. 

BASIC 2 windows can be scrolled, re-sized, moved or closed using the mouse, just 
like other GEM windows. They can also be controlled by using BASIC 2 commands 
and functions. These facilities are described in the next chapter. 

Usually, when text is being output in the bottom line of a window, if the cursor 
attempts to move to the next line, all the text in the window moves up a line to 
make room for the new line, thereby losing the top line of text from the display. 
Text which has disappeared from the top of the window in this way can usually be 
brought back into view by scrolling the window up, using the mouse or BASIC 2 
commands. 

This is because text output is stored in the window's virtual screen; scrolling simply 
moves the window back up the virtual screen. 

Using graphics screens for text output 

As well as the simple text output facilities described previously, graphics screens 
provide these additional facilities: 

- a variety of text fonts 

- a variety of text sizes 

- angled text 

- a variety of write modes (replacing or writing over text/graphics already on the 
screen) 

Text is output using a style which is a combination of a particular text font, text 
size, angle and write mode. You can override the default style within a PRINT 
command by using print functions, or change the default style by using the SET 
command. The styles available, print functions and SET command are described in 
the rest of this chapter. 

Results-1 is initially defined as a graphics screen, so you can use all the facilities 
described in this section, by omitting the Stream number or specifying Stream 
number 1. 









Character 



Position 


The cursor and text positioning 

While in a graphics screen, the cursor can be displayed in three different forms, in 
keeping with its potential use for graphics, text and turtle graphics. 

To change the cursor appearance, use: 

GRAPHICS /# stream] CURSOR style 

style is an integer in the range 1 to 3: 

1 produces + - a crosshair 

2 produces l - a text cursor 

3 produces 4 - a ‘turtle’. 

Text is printed at the cursor position and can be positioned in a graphics screen 
using the LOCATE and print functions AT and TAB described previously. These all 
position text in columns and rows based on the standard system font character size. 

Text can also be positioned more precisely, using the following facilities. This makes 
it easier to fit text around graphics and position output when using different text 
fonts and sizes (as will be described in detail later in this chapter). 

To move the cursor to a position specified in user coordinates, use MOVE: 

HOVE [#stream,] x;y 

The position x;y will be used as the lefthand edge of the base line for the next 
character printed. 

When positions are specified using lines and columns in a graphics screen, these are 
based on the standard character cell size (ie. ignoring the current character size and 
font). To determine the dimensions of the standard character cell, in user 
coordinates, use: 

result = XCELL/I # stream ) ] 
result - YCELL/X#sfream)y 

This can be used, for example, to convert positions and distances from text 
coordinates to user coordinates. 

With the variety of text fonts and sizes available, it can be quite difficult to position 
text exactly, for example when labelling a diagram or centring a line of text. To help 
with this, use the function EXTENT: 

result - EXTENT( [Itstream,] [print-functions,] string-expression ) 

result is the length in user coordinates that the string-expression would have, if the 
print-functions and string-expression were used in a PRINT statement. However, 
EXTENT cannot be used with print-functions and string-expression that include any 
cursor-moving facilities, such as AT. 







To determine the current cursor position, use the following functions: 

result = POS/X #stream) ] 

- horizontal position, as row 

result = X POS/X #stream) ] 

- horizontal position, in user coordinates 

result = VPOS/X # stream ) ] 

- vertical position, as line 

result = Y POS/X # stream ) ] 

- vertical position, in user coordinates 

Text fonts 

As well as the print effects (bold, skewed, etc) described previously (see EFFECTS), 
text can be displayed in a variety of styles, called fonts. BASIC 2 numbers each of 
the fonts you can use, starting from 1. The standard system font (used in text 
screens) is always supplied for the screen and numbered 1. Other fonts may be 
available on your system. 

To discover the numbers and names of fonts supplied with your system, either 
consult the guides supplied with it, or use the function FONTS: 

results = FONTS X [#stream,] font ) 

results is either the name of font number font, or a null string if that, font is not 
available. 

For example, to display the names of all fonts supplied: 

fontno = 1 
REPEAT 

nameS = FONTS(fontno) 

IF nameS < > "" THEN PRINT "Font ";fontno; M is ";name$ 
fontno = fontno + 1 
UNTIL nameS = "" 

To print the following text in a different font, use the PRINT function FONT: 

PRINT [#stream,] [items;] FONT (font); items-2 
This will only affect the font used for items-2. 

To set the default font, use the SET command: 

SET [#stream] FONT font 

While all fonts should display 'normal' characters (with codes in the range 32 - 127) 
as recognisable versions of the corresponding character In the standard system font, 
characters outside this range may or may not be displayed as similar characters 
(check your other guides for details). 

Text size 

Text can be printed in a variety of sizes, measured in 'points'. A point is Vn of an 
inch. The point sizes (ie. sizes of text, in points) available depend on details of your 
system and its fonts. You can find these out by reading the other user guides 
supplied with your computer, or by using the function POINTSIZE: 


result = POINTSIZE ( [#stream,] font, pointsize) 

result is an integer, the next point size available for the font, which is normally less 
than or equal to pointsize. If there is no such point size in this font, the result 
returned is the smallest point size available. In fact, for each point size indicated by 
this function, there is also another that you can use, which is twice the size. 

For example, to print all the point sizes available for a given font (1): 

fontno = 1 
fontsize = 256 

PRINT "Point sizes for font fontno 
REPEAT 

old-fontsize = fontsize 

fontsize = P0INTSIZE(fontno,fontsize-1) 

IF fontsize <> old-fontsize THEN PRINT TAB(6);fontsize 
UNTIL fontsize = old-fontsize 

To print the .following text in a different point size, use the PRINT function POINTS: 
PRINT [^stream,] [items;] POINTS (.points); items-2 
This will only affect the point size used for items-2. 

Text is printed on the same base line regardless of changes in point size. 


BIG TEXT LITTLE TEXT 


To set the default point size (used in subsequent printing), use the SET command: 
SET [#stream] POINTS points 

The point size will be reset if you change fonts or redefine the graphics screen (as 
described in the next chapter). 

The distance that the cursor moves when it prints a line feed depends on both the 
current font and text size and the default character size. It is calculated as the 
base-line to bottom-line distance for the current font and point size, plus the 
top-line to base-line distance for the default character size. 


First Line 


Top Line 


Base Line 


Bottom Line 

-T op Line 

Second Line .. 


■Bottom Un? 










If the characters on the next line are not in the default size then they may overlap. 
To avoid this, use the ADJUST print function instead of POINTS, in the part of the 
print statement that outputs the items in the second line: 

PRINT [#stream,] [items;] ADJUST(po/nis); items-2 

For example: 

SET POINTS 18 

PRINT P0INTS(36); "Major Heading" 

PRINT ADJUST(24); "Subheading" 

PRINT "Actual text" 

which would be displayed as: 

Major Heading 

Subheading 

Actual text 

(The third line of text does not need to be adjusted as it is in the default character 
size.) 

Another way to describe the difference between POINTS and ADJUST is that 
POINTS causes text to be output using the same baseline as the current character 
size, while ADJUST causes it to be output with the same topline as the current 
character size. 

BIG TEXT LimETEXT 


(Note that while the character size is changed by changing the point size, the 
character cell used as the basis for text positioning (LOCATE. PRINT AT. etc) within 
a graphics screen is not. (Remember that you can use MOVE to move the cursor to 
a position specified using user coordinates and use EXTENT to check on the 
displayed length of a piece of text.) 
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Angled text 

Text is normally printed horizontally, but can be printed at any angle, by including 
the ANGLE print function in a print statement: 

PRINT [#stream,] [items;] ANGLE(ang/e); items-2 

angle is in degrees, regardless of the current angle option (see OPTION). For 
example, with an angle of 90. text will be printed vertically! 

To change the default text angle, use the SET command: 

SET /# stream] ANGLE angle 

Note: the angles available are determined by your version of GEM. You will normally 
only be able to use angles that are multiples of 90 degrees. 

Write modes 

Text will normally be printed as a rectangular strip of background on which the text 
is in foreground colour, rather like pasting a strip of printed paper, one character cell 
high, onto the screen. This is called 'replace mode'. 

You can however specify any of four write modes, using the print function MODE: 
PRINT [^stream,] [items;] MODE(wr/te-mocfe); items-2 
write-mode is as follows: 

1 - Replace mode. Prints the text 'over' the current screen contents, as a strip of 
background colour (usually white) containing the text characters in foreground 
colour (initially, black) 

2 - Transparent mode. Prints the text characters only, without affecting the 
background. 

3 - XOR mode. Prints the text characters only, with the colour of each pixel being 
loreground-colour XOR present-pixel-colour. (See XOR in chapter 3.) 

4 - Reverse transparent mode. Prints the background parts of the text only, 
using the foreground colour - producing a sort of 'negative' effect. 

Write mode 1 will produce a result like printing to a text screen, clearing any text or 
graphics out of the way of the text to make sure it is legible. Write mode 2 writes 
the text (but not its background) over what is already on the screen, and is more 
suited to annotating graphics on a screen. Write mode 3 can be used, for example, 
to erase text from the screen (by printing it again with the same text style). Write 
mode 4 provides a simple way to print distinctive headings. 

To change the default text write mode, use the SET command: 

SET /"# stream] NODE write-mode 

Indentation 

When the text cursor moves to the next line as a result of wrapping at the righthand 
edge of the screen, it will normally move to the first character cell of that line. To 
change this, use the print function MARGIN: 

PRINT [^stream,] [items;] MRGUM.position); items-2 



position is an integer expression, specifying the column position, as the number of 
character cells. 

To change the default text margin, use the SET command: 

SET /# stream] MARGIN (.position) 

Default text style 

The default text style is used in text output when the style to use is not stated 
explicitly by print functions. It can be changed by using the SET command, as 
already described: 

SET [#stream] options 

where options is a list of any of the following options, separated by spaces. 

ZONE zone-width 

- print zone width 

COLOUR colour 

- foreground colour 

EFFECTS effects-1 [,effects-2] 

- text style 

WRAP switch 

- automatic carriage return/line feed at right edge of screen (switch is ON or OFF) 

FONT font-number 

- text font 

POINTS points 

- text size 

ANGLE angle 

- text angle 

MODE write-mode 

- write mode 

MARGIN margin 

- text margin 

(The first four options were described in the first section, on simple text output; the 
others in this section.) 

The default text style for the screen attached to the default stream can also be 
changed by using the Fonts menu. 

The default text style is reset to its initial state when BASIC 2 is first entered or 
when the graphics screen is redefined (see the next chapter) or cleared using CLS 
RESET. This initial state is described in the Appendix HI. 

Escape sequences 

All the escape sequences (and control codes) described in previous sections of this 
chapter can be used with graphics screens. Note that if writing text at an angle, the 
'up' direction used when obeying sequences such as line feed and ESC I wiil be 
relative to that angle. ESC is character code 27. 
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In addition, the following escape sequences can be used to alter the default text 
style, instead of SET: 

Escape sequence Effect 

ESC P n+32 POINTS(n) 

ESC F n+32 FONT(n) 

ESC X (n/5)+32 ANGLE(n) - note increments of 5 degrees 

ESC W n+32 MODE(n) 

Using text screens for text output 

This section describes the facilities provided for handling text output on text 
screens, in addition to those described for simple text output, at the beginning of 
this chapter. 

Results-2 is initially set up as a text screen attached to Stream #2, so you can use 
the facilities described here by specifying a Stream number of 2. 

Text screens cannot produce quite such glamorous displays as graphics screens, but 
have the advantage of considerably faster operation and greater text storage. 

Clearing a text screen 

To clear the whole screen, use CLS or CLS RESET as described previously. 

A number of other screen-clearing facilities are provided by: 

TEXT CLEAR quantity 

where quantity is one of the following: 

EOL clear from the cursor to the end of the line inclusive 

BOL clear from the beginning of the line to the cursor inclusive 

LINE clear the whole line containing the cursor 

EOS clear from the cursor to the end of the screen inclusive 

BOS clear from the beginning of the screen to the cursor inclusive 

SCREEN clear the entire screen (equivalent to CLS) 

To delete an area of the screen, ie. to remove it and pull in the surrounding text to 
replace it, use: 

TEXT DELETE to delete the character at the cursor 

TEXT DELETE LINE to delete the line containing the cursor 


Other text commands 

To move the cursor a number of lines up or down the screen, use the command 
TEXT FEED: 

TEXT FEED lines 

The window will scroll to keep the cursor visible, if this is necessary. 

(If lines is negative, the cursor moves upwards.) 



To insert a line ie. to move all text below and including the cursor line down a line 
and leave a blank line, use: 

TEXT INSERT LINE 


Escape sequences 

As an alternative to using the TEXT and CLS commands, you can print the 
following escape sequences: 


Sequence 

ESC E 
ESC J 
ESC K 
ESC L 
ESC M 
ESC N 
ESC d 
ESC 1 
ESC o 


Effect 

clear screen and move cursor to top left 

clear to end of text screen 

clear to end of line 

insert blank line 

delete line 

delete character 

clear from start of text screen to cursor 
clear whole line 

clear from beginning of line to cursor 


ESC E is equivalent to the CLS command. The other sequences are equivalent to the 
TEXT CLEAR, TEXT DELETE and TEXT INSERT commands. 


Using a printer for text output 

Text output to a printer is similar to output to the screen, but is rather more limited. 
In particular, there is no windowing and many printers will not print the accented 
characters, greek symbols or print effects as they are displayed on the screen. 

However, if your printer is 'IBM-compatible’, it should print characters with codes 
other than 176 - 207 as they are displayed in the standard text font. 

Text can be printed on the standard printer (PRN) using the command LPRINT, 
which is in many ways similar to PRINT. LPRINT can be used to print lists of items, 
with semicolons and commas having the same effects as with PRINT. Of the print 
functions, only TAB(x) can be used. The TAB character (Control-I) will be output as 
Control-I, rather than expanding it to a number of spaces. 

The standard printer is actually attached to Stream 0, which can be used in the 
following commands, only: 

PRINT #0: text output 

PRINT #0 USING: formatted text output 

CLOSE #, OPEN #: see below 

STREAM #0: see chapter 6 

Stream 0 can be used in a similar way to streams attached to screens. So, if output 
commands use a 'pseudoconstant' to specify the stream for output, you could 
switch output to the printer (or a different window or even a disc file) by simply 
changing the value assigned to that variable. 
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You can also use other streams for printer output, after defining them using the 
command OPEN PRINT: 

OPEN # stream PRINT [device-number] 

A device-number of 0 specifies the standard printer, PRN, 1 to 3 specifies 
LPT1 - LPT3, 4 to 5 specifies COM1 - COM2. PRN is also assumed if device- 
number is omitted. (See your other guides for details of these devices.) 

A printer can be open on more than one stream at a time. 

To close a printer stream, use: 

CLOSE #stream 

The LPRINT command always outputs to Stream 0, so that changing Stream 0 will 
also affect its output. 

Note that BASIC 2 does not interpret or trap control codes and escape sequences in 
output routed to a printer, so if you want to control the printer, you can simply 
include the appropriate codes in print statements that output to its stream. Refer to 
the printer user guide for details of the escape sequences and control codes it 
obeys. 

Graphics output 

Graphics output consists of dots, straight lines, curves, patterns etc, usually 
combined to produce pictures such as pie charts, engineering drawings, 
self-portraits, etc. 

This section describes how to output graphics to a display. You can also use most 
of the facilities described here with other graphics devices, as described in the next 
chapter. 

The graphics objects that can be drawn with single commands are: 

- points and markers 

- straight lines 

- rectangles 

- polygons 

- circles and parts of circles 

- pie segments 

- ellipses and elliptical pie segments 

(Of course, more complex graphics can be produced by combining these.) 

Graphics can be drawn in a variety of colours (or intensities on a monochrome 
monitor), line styles and line widths. Closed figures (such as circles and polygons) 
can be drawn as outlines or solids filled with a variety of patterns. Line graphics can 
also be drawn by driving a ‘turtle’ around the screen. 

To see the colours, patterns, line styles, line widths etc. available, select the 
Colours, Patterns and Lines menus with your mouse. 

Text can also be mixed with graphics, as described earlier in this chapter. 
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By default, all output is routed to Stream 1. Graphics can, however, be output to 
other streams by including the stream number in the output command, provided 
that the stream has been set up for graphics. Graphics can only be output to 
graphics screens and other graphics devices. Graphics cannot be output to text 
screens. 

Graphics units and positions 

User coordinates are used for all graphics output commands. 

A screen’s user coordinates are automatically defined so that graphics will be 
correctly proportioned when displayed, correcting for any asymmetry in its pixels. 
This is done by treating the screen as a rectangle, whose shorter edge is 5000 user 
coordinates long; the length of the longer edge is automatically set to adjust for the 
physical difference. 

For most purposes, you can simply imagine that you are drawing graphics on a 
square of 5000 x 5000 user coordinates - that’s the approximate size of the area of 
Results-1 initially visible on your display. The same approach is also used for other 
graphics devices, making it very simple for you to switch between using different 
output devices. (See the next chapter.) Graphics screens (and devices) are 
automatically set up so that graphics are undistorted, with square squares and 
circular circles, etc. 

You can check the screen’s size in user coordinates (see XVIRTUAL and YVIRTUAL, 
below) and redefine the size of user coordinates (see USER SPACE, in the next 
chapter), if you wish. 

Positions in a graphics screen are specified as x;y, where x and y are the distance in 
user coordinates away from the screen's 'graphics origin’, in the X (horizontal) and Y 
(vertical) direction. 

The graphics origin is initially set to the bottom left corner of the graphics screen, 
but this can be changed, as described in the next chapter (see USER ORIGIN). 

When specifying a position in a graphics output command, you may omit x, y, or 
both and the current coordinates of the cursor will be used instead. If a single 
parameter is given, it will be taken as the x position unless preceded by a semicolon 
(;), when it will be taken as the y position. 

All user coordinates used in graphics commands must lie within the graphics 
screen, or an error will result. You can determine the size of a graphics screen, in 
user coordinates, by using: 

width = XVIRTUAL/Y#sfream) ] 
height = YVIRTUAL [(#stream)] 

Drawing graphics 

Graphics are drawn using commands of the form: 

command [#stream,] mandatory-parameters [optional-parameters] 

The # stream part is optional: if omitted, output is to the default stream (ini ti a l ly 
Stream 1). This stream must be a graphics screen or graphics device. Stream 1 is 
automatically set up as a graphics screen when BASIC 2 is entered (see the next 
chapter for details of how to define a graphics screen). 



The mandatory-parameters must be supplied, and in the sequence shown in the 
command description. They are integer expressions, separated by commas. (But see 
Positions, below). 

The optional-parameters can be omitted or supplied in any. order, after the 
mandatory-parameters. They consist of keywords, sometimes followed by integer 
expressions. These keywords must be preceded by spaces, as shown. 

Mandatory parameters specify essential aspects of the object to be drawn, like the 
position and radius of a circle. 

Optional parameters specify details of the style of the object to be drawn, such as 
colour or line style. Any aspects of the style which are not stated explicitly by the 
optional parameters will default to those in the ‘default graphics style’ (see 
GRAPHICS). 

Points and lines 

To plot a single point or series of points with markers, use the command PLOT: 

PLOT [#stream,] points /MARKER marker-type] /SIZE marker-size] 

/■COLOUR colour] /MODE write-mode] 

Note that this is a single command, shown like this because of the limitations of the 
printed page. 

This plots markers, centred on the points specified by points, points is a list of one 
or more coordinate pairs. The coordinates in a pair are separated by a semicolon; 
coordinate pairs are separated by commas. 

If the optional keywords are omitted, points will be plotted in the default graphics 
style. The first three optional keywords allow you to control the style of the markers 

- their type, size and colour, as follows: 

marker-type is an integer expression, which determines the style of marker used. 
marker-types 1 to 6 are defined as a dot, plus, asterisk, square, diagonal cross and 
diamond. Other types may be available - see Appendix III. 

marker-size is an integer expression in the range 0-15, which determines the size 
of marker used. If not available, the next smallest size available is used. 

colour is an integer expression, which determines the colour (intensity) of the 
marker, colours 0 (white) and 1 (black) are always available; others depend on your 
computer. 

write-mode is an integer expression in the range 1 - 4, that specifies how graphics 
objects are written to the screen: 

- 1: Replace mode. Draws 'over' the current screen contents, so that parts of the 
object which are in the background colour (normally white) will be drawn, as well 
as the parts that are in the foreground colour. 

- 2: Transparent mode. Draws the foreground parts of the object only; parts in the 
background colour will not be drawn. 

- 3: XOR mode. Draws the foreground parts only, as colour XOR present-pixel- 
colour. This can be used, for example, to erase an object by plotting it again. 

- 4: Reverse transparent mode. Draws the background parts of the object only, in 
the foreground colour, producing a sort of 'negative' effect. 



As markers consist of lines in foreground colour only (no background), the 
transparent and replace modes of PLOT are equivalent and reverse transparent mode 
draws nothing! 

These optional keywords may follow points in any order. 

To see the line colours and types available, select the Colours and Lines menus with 
the mouse. These can also be used to change the default line colour and line type 
on the default stream. 

The optional keywords only affect the style of the markers being plotted by the 
command; they do not affect the default graphics style (see SET). 

To draw straight lines, use the command LINE: 

LINE [#stream,] points /WIDTH line-width] /STYLE line-style] /COLOUR colour] 
/MODE write-mode] /START line-start] /END line-end] 

Note that this is a single command, shown like this because of the limitations of the 
printed page. 

This draws a line between each point specified. For example, to draw a triangle; 
LINE 2000;2000, 2000;4000, 4000;2000, 2000;2000 STYLE 2 
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If the optional keywords are omitted, lines will be drawn in the default line style. 
The optional keywords allow you to control the style of the line drawn, as follows. 
COLOUR and MODE are as described previously. 

line-width is an integer expression which determines the thickness of the line in 
pixel widths, after being rounded down to the nearest odd number. 





































line-style is an integer expression which determines whether the line should be 
continuous, dotted, dashed etc. line-styles 1 to 6 are always available and are 
described in the appendices. (Other line-styles may also be available, depending on 
the device.) Dotted and dashed lines often can only be drawn if the line width is set 
to 1. This limitation is determined by your computer. 

line-start and line-end are integer expressions in the range 0-2. They define the 
style used for each end of the line: squared, arrow and rounded, respectively. 

To see the styles available, select the Colours and Lines menus with the mouse. 
These can also be used to change the default line colour and line type for the 
default stream. 

The optional keywords only affect the style of the lines being drawn in that 
command. 


Circular curves and figures 


To draw a circle or part of a circle, use the CIRCLE command: 

CIRCLE [#stream,] x;y, radius /PART start-angle, end-angle] 

/START start-style] /END end-style] 

/WIDTH line-width] /STYLE line-style] /COLOUR colour] 

/MODE write-mode] /FILL /ONLY/ /WITH fill-style]] 

Note that this is a single command, shown like this because of the limitations of the 
printed page. 

This draws a circle with its centre at x;y and the specified radius and fills it if 
required. The START. END, WIDTH, STYLE, COLOUR and MODE keywords are as 
described previously. 

PART is used to draw part of a circle, from start-angle to end-angle. These angles 
are specified in an anticlockwise direction, with 0 being along the positive x axis 
(‘East’): 

(The units usually used for angles are radians, but see OPTION DEGREES.) 


90 degrees 



k/2 radians 


180 degrees 
it radians 


0 degrees 
0 radians 


270 degrees 


3tc/ 2 radians 





FILL specifies that the circle should be filled with a colour or pattern, after its 
circumference has been drawn, fill-style is an integer expression specifying what to 
fill with - refer to Appendix III for details. If FILL ONLY is specified, the circle will 
only be filled; no circumference will be drawn. 

For example: 

CIRCLE 2500;2000, 1500 
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CIRCLE 2500;2000, 1500 PART RAD(45),RAD(135) START 1 END 1 
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Note that while all positions specified in graphics commands must lie within the 

virtual screen, you may draw figures such as circles even if part of them would lie ; 

outside the virtual screen. For example: 

CIRCLE 500;500, 3000 FILL WITH 5 j 



(This may however not be true when using other graphics devices.) 
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To draw a pie segment (sector of a circle), use the command PIE: 

PIE /# stream,] x;y, radius , start-angle , end-angle /WIDTH line-width] 

/STYLE line-style] /COLOUR colour] 

/MODE write-mode] /FILL /ONLY/ /WITH fill-style]] 

This draws an arc centred on x;y, with the specified radius, from start-angle to 
end-angle, then draws radii to the ends of the arc and fills it if required. The 
optional keywords are as for CIRCLE. 

For example: 

PIE 3000;800, 2000, RAD(90), RAD<180) FILL WITH 3 STYLE 5 
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(PIE is equivalent to CIRCLE with PART and FILL specified.) 


Elliptical curves and figures 

There are also elliptical versions of CIRCLE and PIE. These are usually used to 
produce ellipses, ovals, etc. They can also be used to produce figures that look 
circular on displays (or other devices) that are not equally proportioned horizontally 
and vertically (ie. that have an aspect ratio other than 1), either because you've 
redefined the device's user coordinates that way (see USER SPACE), or because the 
device is not addressed using user coordinates. 








































These commands are ELLIPSE (squashed circle) and ELLIPTICAL PIE. They behave 
exactly like the non-elliptical versions, except that aspect is added after radius in 
each case ie: 

ELLIPSE [#stream,J x;y, radius, aspect /PART start-angle, end-angle] 

/START start-style] /END end-style] 

/WIDTH line-width] /STYLE line-style] /COLOUR colour] 

/MODE write-mode] /FILL /ONLY; /WITH (ill-style]] 

ELLIPTICAL PIE /# stream,] x;y, radius, aspect, start-angle, end-angle 
/WIDTH line-width] /STYLE line-style] /COLOUR colour] 

/MODE write-mode] /FILL /ONLY/ /WITH (ill-style]] 

Note that these are single commands, shown like this because of the limitations of 
the printed page. 

aspect is a positive number (usually not an integer). When the figure is drawn, the 
radius in the Y dimension is taken as radius *aspect; the radius in X is 
unchanged. 

Polygons 

Most figures can be constructed using the point, line, circle and ellipse-drawing 
commands, but common types such as rectangles and polygons can be drawn more 
quickly and easily using their own commands. These commands also make it very 
easy to produce solid rather than outline shapes, as described below. 

To draw any polygon, use the command SHAPE: 

SHAPE /# stream,] points /WIDTH line-width] /STYLE line-style] 

/COLOUR colour] /MODE write-mode] /FILL /ONLY/ /WITH (ill-style]] 

Note that this is a single command, shown like this because of the limitations of the 
printed page. 

This command draws lines (unless FILL ONLY is specified - see below) between 
each specified point, finishing by drawing from the last point back to the first. 

The first four optional keywords are as described under Points and lines, above. FILL 
is as described for Circular curves and figures. 



For example, to draw a solid diamond: 

SHAPE 3000;0/ 2000;2000, 3000;4000, 4000;2000 FILL ONLY WITH 1 
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To draw a rectangle with horizontal and vertical sides, use the command BOX: 

BOX [tstream,] x;y, width,height /WIDTH line-width] 

/STYLE line-style] /COLOUR colour] /MODE write-mode] 

/FILL /ONLY;/WITH fill-style]] [ ROUNDED/ 

Note that this is a single command, shown like this because of the limitations of the 
printed page. 

This draws a rectangle with its bottom lefthand corner at x;y, giving it the specified 
width and height, then filling it if required. The optional keywords are as for SHAPE, 
with the exception of ROUNDED, which produces a rectangle with rounded comers.' 









































































For example, to draw a filled square with rounded comers: 

BOX 500;500, 4000, 4000 FILL WITH 3 ROUNDED 
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Filling areas of the screen 

To 'flood fill' a bounded area of the screen, use the FLOOD command: 

FLOOD [#stream,] x;y [, limit] /COLOUR colour] 

/MODE write-mode] /FILL /WITH fill-style]] 

Note that this is a single command, shown like this because of the limitations of the 
printed page. 

limit is an integer expression in the range 0 to 15, specifying a (boundary) colour. 
The other parameters are as described previously, for circles. 

This command fills the screen with the specified or default fill style and colour, 
beginning at x;y and spreading out from that point in all directions. Filling only 
stops when the next pixel to be filled has a 'boundary' colour. If limit is specified, 
this is the 'boundary' colour, otherwise it is taken as the colour you are filling with. 

Note that filling will only take place within that part of the screen visible in its 
window, so that x;y must be in the window for filling to occur at all. Filling will 
finish not only at the window edge, but if it meets the edge of another window. 

It follows that if you want to fill a picture 'correctly'. you must make the window full 
size (ie. the same size as its virtual screen) and the top window (see WINDOW 
OPEN). 

NOTE: This feature may not be available on your computer, as it depends on the 
version of the underlying software that you are using. 





























































































































































Testing points 

To read the colour of a point being displayed in a graphics window, use the function 
TEST: 

result - TEST (/#sfream,/x;y) 

result is -1 if the specified point is not being displayed, otherwise it is the colour 
code for that point, in the range 0 - 15. 

Default graphics style 

The default graphics style can be changed using the GRAPHICS command, as 
follows: 

GRAPHICS /# stream] options 

where options is a list of any of the following options, separated by spaces: 

COLOUR colour 
MARKER marker-style 
MARKER SIZE marker-size 
/LINE; WIDTH line-width 
/line; STYLE line-style 
/line; START start-style 
/LINE; END end-style 
FILL /WITH /STYLE/ fill-style] 

MODE write-mode 
CURSOR cursor-type 

The significance of each option should be obvious from the previous description of 
the output command options. 

The default graphics style for the default stream can also be changed using the 
Colours, Lines and Patterns menus. 

The default graphics style is used for any aspect of a graphics output operation not 
stated explicitly in the output command. It is reset to an initial state when BASIC 2 
is first entered, or the graphics screen is redefined (see the next chapter) or reset 
(CLS RESET). This initial state is described in Appendix E. 

Turtle graphics 

As well as drawing graphics using the above commands, you can choose to use a 
number of simple graphics commands to drive a cursor around the screen, drawing 
as it goes. This type of graphics output may be familiar if you have used the LOGO 
programming language - it is usually called ‘turtle graphics’, because the movement 
of the cursor resembles that of a turtle. 

Note that while you can mix turtle graphics output with other graphics and text on 
the same screen, all output uses the same cursor, so you will have to control its 
position carefully. 

The turtle graphics commands are: 

GRAPHICS /# stream] CURSOR 3 

This sets the cursor appearance to a ‘turtle’: a box with an arrow on it, showing the 
turtle's current heading (initially, 0: to the right). 



LEFT [#stream,] angle 

This makes the turtle turn through angle, anti-clockwise. LEFT may be abbreviated 
to LT. (Angles will normally be in radians, but see OPTION DEGREES.) 

RIGHT [#stream,] angle 

This makes the turtle turn through angle, clockwise. RIGHT may be abbreviated to 
RT. 

POINT [#stream,] heading 

This makes the turtle turn to the specified heading. 


90 degrees 
jt/2 radians 
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/move; FORWARD [#stream,] distance /WIDTH line-width) 

/STYLE line-style] /COLOUR colour] /MODE write-mode] 

/START line-start] /END line-end] 

Note that this is a single command, shown like this because of the limitations of the 
printed page. 

This moves the turtle forward distance user coordinates on its current heading. If 
MOVE is not specified, the turtle will draw a line as it goes. The other parameters 
are as described previously for LINE. 

(FORWARD may be abbreviated to FD.) 

The turtle graphics functions are: 

result = HEADING [(.# stream) ] 

- returns the current turtle heading (angle) 

result = TOWARDC [#stream,] x;y) 

- returns the heading the turtle would have to point to. to reach position x;y (which 
is in user coordinates). 

result = DISTANCE(/#sfream,/ x;y) 

- returns the distance the turtle would have to move, to reach position x;y (user 
coordinates). 





These functions can be used, for example, to draw from the current position to a 
particular position: 

head = TOWARD(targetx;targety) 
far = DISTANCE(targetx;targety) 

POINT head 
FORWARD far 




6. ADVANCED TEXT AND GRAPHICS 


The previous chapter has described how to output text and graphics to the display, 
using the default virtual screens and windows and controlling windows with the 
mouse. This chapter describes a number of more advanced facilities: 

- device coordinates (pixels) 

- the relationship between streams, virtual screens and windows 

- defining and controlling windows 

- defining virtual screens 

- redefining user coordinates 

- using the mouse 

- summary of functions 

- using other devices 

Device coordinates (pixels) 

As described in the previous chapter, text coordinates and user coordinates are used 
for positioning and measurements within virtual screens. A third coordinate system, 
used for positioning and measurements on the display or other graphics output 
device, is based on 'pixels’. 

Pixels are the smallest 'picture elements' that the device can resolve separately, 
hence they are also known as 'device coordinates'. On a display, pixels are the 
individual phosphor dots that the display makes bright or dark to produce an image, 
while on a dot matrix graphics printer, they are the dots produced by individual 
print needles striking the ribbon. 



a pixel 


usable area 
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The number of pixels across and down your display determines the displayed quality 
('resolution') of pictures it can display. This depends on the type of graphics 
circuitry fitted to your computer (see XDEVICE, YDEVICE), but a common display 
resolution is 640 pixels across, by 200 down. This resolution will be assumed in the 
examples given here, although this assumption is not crucial. 

Pixels are used for all measurements and positioning on the display (as opposed to 
virtual screen) or other output device. Positions are expressed as x;y, where x and y 
are the position's distance (in X and Y dimensions) from the bottom left comer of 
the display. 

Positions specified using pixels must lie within the dimensions of the usable display 
area, or an error will result. You can determine the size of this area by using the 
following functions: 

width = XDEVICE[(#sfream) ] 
height - YDEVICE ((#stream)] 

where width and height gives the overall device size in pixels, 
or 

width = XUSABLE/<#sfream) ] 
height = YUSABLE/(#sfream) ] 

where width and height give the usable device size, in pixels. For your computer's 
display, XUSABLE and XDEVICE will be the same, but YUSABLE will be less than 
YDEVICE, because of the presence of the GEM menu line. 
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Streams, virtual screens and windows 

The description of output to the screen in Chapter 5 glossed over many details of 
using streams, virtual screens and windows. 

BASIC 2 allows you to use up to 16 different streams (0 - 15). Each stream 
effectively gives you access to a different output device. Streams 0 - 2 are set on 
entry to BASIC 2 as: 0 as the (text) printer, 1 as the Results-1 virtual screen and 2 
as the Results-2 virtual screen. 

If you want to use any other streams, you must define them first, as a text output 
device (OPEN PRINT), a graphics output device (OPEN DEVICE) or a window onto a 
virtual screen (OPEN WINDOW). These commands can also be used to switch 
existing streams from one device to another, after closing the stream first (CLOSE). 

Once a device has a stream set up for it, you can use that device for output, by 
specifying its stream number in the output command, as described in Chapter 5. if 
no stream number is specified, output will go to the default stream, as described 
below. 

This chapter will concentrate on using the display ie. using windows and virtual 
screens. Details of using other devices are given at the end of the chapter. 

BASIC 2 allows you to use up to four virtual screens (with their associated 
windows), numbered 1 to 4. These behave almost as separate output devices, even 
though they ah use the same real device: the display. 

When text or graphics is output to the display, it is stored in and formatted to fit the 
virtual screen used. Each virtual screen has a window, which is usually smaller than 
the virtual screen. The window reveals only part of the contents of its virtual screen, 
and can be moved to reveal different parts (scrolled), changed in size, made invisible 
(closed) or visible again (opened), moved over the display, etc. 

A virtual screen is rather like a private world, populated by the text and/or graphics 
information which has been output to its stream. The stream's window serves as a 
peephole onto this private world, limiting and framing the view. 



When you output text or graphics to a virtual screen, you only see that part of the 
output that falls within the area of the virtual screen shown in its window. To see 
more, you scroll the window 'over' the larger picture, drawn previously on its virtual 
screen. 
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Windows have a variety of useful properties and can be manipulated using BASIC 2 
commands and the mouse, or examined using BASIC 2 functions. 

Note that, as far as your programs are concerned, output is not to the real display, 
nor to a window on the real display, but to virtual screens. This enables you. for 
example, to write programs that can adapt to using displays with different 
dimensions and resolutions and to use several 'separate' screens at once on a single 
display. 

The standard streams , screens and windows 

The four screens/windows provided are numbered 1 to 4. They are set up initially as 


follows: 

Stream 

Window 

Window 

Type 

Usual function 

1 

1 

name 

Results-1 

graphics 

default text and graphics output 

2 

2 

Results-2 

text 

additional text window 


3 

Edit 

text 

additional text window. See 


4 

Dialogue 

text 

warning below 
additional text window. See 




warning below 


The first two virtual screens are reserved for use by your programs and will suffice 
for most needs. You could also use the other two virtual screens, but their main use 
is in Direct mode, for the Dialogue and Edit windows. As a result, any output in 
screen 4 will be lost when a program stops, while any output in screen 3 will be lost 
if you use the edit window. 

For an explanation of the screen descriptions and how to redefine screens, see 
‘Defining virtual screens', below. 

Controlling and using streams 

As described in Chapter 5, text and graphics commands all, by default, use the 
default stream. This is initially Stream 1. attached to Window (virtual screen) number 
1 - the Results-1 window (but see STREAM, below). 

To use a different window, specify its stream number, preceded by a '#', in the 
output command. If the next item after the stream number is not a keyword, the 
stream number must be followed by a comma. 

For example, using PRINT: 

PRINT ^stream, print-items 

PRINT #stream USING format-template ; using-list 

Commands will normally use Results-1 if no stream number is specified, because its 
stream (stream 1) is the default stream when a program is run. You can change the 
default stream, by using the command STREAM: 

STREAM ^stream 

For example: 

STREAM #picture 



After this, commands that do not specify a stream will default to using the stream 
'picture'. You could use this, for example, to switch all default stream output from 
the screen to a printer (stream 0), plotter, or even a disc file (see Chapter 8)1 

The relationship between streams and virtual screens can be changed using the 
commands CLOSE and OPEN WINDOW, as follows. 

To close a virtual screen and window, discarding all its contents and making it 
invisible, use: 

CLOSE #stream 

You can then reassign that stream and window, using: 

OPEN #stream WINDOW window-number 

window-number is an integer expression in the range 1-4 and must not be 
already open, stream is an integer expression in the range 0-15 and must not be 
already open. 

This command associates the stream number with the specified window and virtual 
screen. The virtual screen and its window will be defined as they were when last 
used (ie. virtual screen type, window scroll position, etc), except that the virtual 
screen contents will be lost and attributes such as the text and graphics colours and 
styles will be returned to default. The window will be invisible initially (see 
WINDOW OPEN, below.) 

You can use this method, for example, to attach the Results-2 window (Window 2) 
to Stream 1: 

CLOSE #1 
CLOSE #2 

OPEN #1 WINDOW 2 

If a stream is closed when an instruction attempts to write to it, an error will occur. 
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As described above, windows are used to show the contents of virtual screens on 
the display. BASIC 2 windows can be manipulated using the mouse, like other 
GEM windows, but can also be manipulated using BASIC 2 commands and 
functions. These allow you to control the following aspects for each window, 
independently: 

- visibility 

- position within its virtual screen (scrolling) 

- size 

- position on the display 

- legends 

Window visibility 

The visibility of a window is controlled using the commands WINDOW OPEN and 
WINDOW CLOSE. WINDOW CLOSE removes a window from the display but 
preserves its contents (ie. its virtual screen): 

WINDOW [# stream] CLOSE 

while WINDOW OPEN makes it visible again, with all its contents intact, in its last 
defined position: 

WINDOW [#stream] OPEN 

This also makes this window the top window (ie. places it 'in front of' any 
overlapping window on the display). 

Note the difference between closing a stream (loses the virtual screen and window) 
and closing a window (simply makes it invisible). 

Finally, to remove a window from the display by using its window number, you can 
use CLOSE WINDOW: 

CLOSE WINDOW window-number 

•This command is mainly intended for removing the Edit (window number 3) or 
Dialogue (window number 4) windows from the display. (You cannot use WINDOW 
CLOSE for this, since these windows are not attached to streams.) 

You can also control window visibility by selecting options from the Windows menu 
with your mouse. 

Scrolling 

Usually, when text is being output in the bottom line of a window, if the cursor 
attempts to move to the next line, all the text in the window moves up a line to 
make room for the new line, thereby losing the top line of text from the display. 
Text which has disappeared from the top of the window in this way can usually be 
brought back into view by scrolling the window, using the mouse or BASIC 2 
commands. 

This is because text output is stored in the window's virtual screen; scrolling simply 
moves the window back up the virtual screen. 



To scroll a window with the mouse, drag the appropriate scroll bar. 

To scroll a window from a program, use the command WINDOW SCROLL: 

WINDOW [#stream] SCROLL x;y 

This makes point x;y (user coordinates on a graphics screen, text coordinates on a 
text screen) the bottom left point in the window. The position will be modified, if 
necessary, to keep all of the window inside the virtual screen. 

Scrolling in effect moves a window over its virtual screen. It is the size of the virtual 
screen (see SCREEN) which determines whether scrolling can occur and if so. how 
far it can go. 

A window can only be scrolled in directions in which there is more of its virtual 
screen to reveal. This is affected by the virtual screen's definition. For example, if a 
screen's width were defined as FIXED (see SCREEN), you could not scroll its 
window horizontally - in fact, you could see that this was the case, because it 
would be displayed without a horizontal scroll bar. 

To determine the current position of a window in its virtual screen, use the 
functions XSCROLL and YSCROLL: 

result = XSCROLL [(.^stream) ] 
result = YSCROLL/X#sfream) ] 

These return the position of the bottom left comer of the window, in user 
coordinates. 

The cursor is turned off, by default. Text output is stored in the virtual screen, but 
will only be visible if written to that area of the virtual screen shown in the window. 

To produce automatic scrolling, turn the cursor on: 

WINDOW [#stream] CURSOR ON 

The window will then scroll to display the cursor when text is next output to that 
screen and scroll automatically thereafter to keep the text being output in view. 

To turn the cursor (and automatic scrolling) off again: 

WINDOW [#stream] CURSOR OFF 

When text output reaches the limits of a screen, the screen itself will ALWAYS scroll 
to make room for more text, thereby losing the 'topmost' line of text for ever. This 
will also cause the window's contents to scroll. 

Window size 

Windows can be moved or resized by the user with the mouse, as described in your 
other guides. BASIC 2 provides similar facilities for use in programs, as follows. 

To change a window's size, use the command WINDOW SIZE: 

WINDOW [#stream] SIZE width, height 

width and height specify the new dimensions in pixels. These will be rounded up to 
satisfy any UNIT specification for this window in its virtual screen definition (see 
SCREEN), subject to any limits imposed by MAXIMUM and MINIMUM. For a text 
window, the size will be rounded to a whole number of columns and lines 
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To make a window full size, use: 

WINDOW [#stream] FULL ON 

This sets its displayed size as large as allowed by the display (subject to any 
maximum specified using SCREEN). To restore the window to its previous size, use: 

WINDOW l#stream] FULL OFF 

To determine the current size of a window (in pixels), use the following functions: 
result = XWINDOW/(#sfream) ] 
result = YWINDOW/X#s/ream) ] 

where result gives the size of the usable portion of the window, ie. the part that 
displays the contents of the virtual screen. 

result = XACTUAL/X#sfream) ] 
or result = YACTUALf(#sfream) ] 

where result gives the overall size of the window, including its scroll bars, title and 
information line. 

To determine the size of a window's scroll bars and title line, use the following 
functions: 

result = XBkR[(# stream) ] 

where result is the width (in pixels) of the vertical scroll bar 
result = VBAR[(.# stream) ] 

where result is the height (in pixels) of the horizontal scroll bar 

The height of the title bar (in pixels) can be calculated using a combination of these 
functions, as follows: 

result = YACTUAL/Y#sfream) ] - YWINDOW/X#sfream) ] - YBARf(#sfream) ] 

Window position 

To change the position of a window on the display, drag it using the mouse, or use 
the command WINDOW PLACE: 

WINDOW [#stream] PLACE x;y 

x and y specify the new position on the display of the bottom left corner of the 
window, in screen coordinates (pixels). 

To determine the current position of a window on the display, use the functions 
XPLACE and YPLACE: 

result = XPLACE/X #stream) ] 
result - YPLACE/( #stream) ] 

The results give the position of the bottom left corner of the window, in screen 
coordinates (pixels). 

If two windows overlap, to avoid confusion, one is always displayed as if it were on 
top of the other ie. in the overlapping region, only that window's contents will be 
displayed. To make a window the top one, use: 

WINDOW [^stream] OPEN 



Window legends 

To change the title of a window (as displayed in its title bar), use: 

WINDOW [#stream] TITLE string-expression 
To change the information line of a window, use: 

WINDOW [#stream] INFORMATION string-expression 

(the information line is only displayed if specified when defining the screen. See 
Defining virtual screens, below.) 

Defining virtual screens 

All four virtual screens are set up for you when you enter BASIC 2, as described 
previously. If you want to redefine these screens, you should use the SCREEN 
command, as described here - for example, to produce four graphics screens, or 
screens of particular sizes. 

Note that all four screens will return to these default definitions when you use the 
CLEAR RESET command or reselect BASIC 2. Screen 3 will also revert to the 
default if you use the Edit window when in Direct mode. Screen 4 will also revert to 
the default as soon as the program ends. 

The screen’s stream must be open before you start to redefine it. 

Defining a text screen 

To define a text screen, use the SCREEN TEXT command: 

SCREEN [#stream] TEXT dimensions /MINIMUM w ,h] /MAXIMUM w,h] 

/UNIT w,h] /INFORMATION switch] 

where dimensions is: 

FLEXIBLE 

or width /FIXED;, height /FIXED; 

For example: 

SCREEN #2 TEXT 40 FIXED, 20 INFORMATION ON 

The optional # stream specifies the virtual screen to redefine. If omitted, the default 
output stream is assumed. 

TEXT specifies that the screen is a text screen. 

FLEXIBLE forces the width of the virtual screen to the same as its window and to 
change with it whenever it changes, re-arranging the text displayed, accordingly. 
The capacity {width * height) of a FLEXIBLE screen is constant, at about 2000 
characters. 

width and height specify the virtual screen dimensions, in columns and lines. If 
FIXED is appended, that dimension of the window is forced to the same as the 
virtual screen. The maximum volume capacity for a text screen depends on the 
computer, but a sensible limit is 2000 characters. 
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MINIMUM specifies a minimum width (w) and height (h) for the window, in columns 
arid lines. MAXIMUM specifies a maximum. If omitted, these limits default to give 
approximately 18 columns and 6 lines (minimum) and the maximum size permitted 
on the display, respectively. 

UNIT specifies the units by which the window size will be allowed to change 
(lines/columns). If omitted, this defaults to one character. 

INFORMATION switch is ON or OFF. ON specifies that the window should have an 
information line (see WINDOW INFORMATION). 

The SCREEN command clears the virtual screen (and window) and resets its user 
origin, user coordinates, text and graphics colours, etc. If possible, the ament 
window size is left unchanged. If the window is open, it is made the top window. 

Defining a graphics screen 

To define or redefine a graphics screen, use SCREEN GRAPHICS: 

SCREEN /# stream / GRAPHICS width /FIXED/, height /fixed/ 

/Minimum w,h] /maximum w,h] /unit w,h] /information switch] 

(Note that this is a single command: it is simply spread over several lines for clarity.) 

The optional #stream specifies the virtual screen to redefine. If omitted, the default 
output stream is assumed. 

GRAPHICS specifies that the screen is a graphics screen. 

width and height specify the size of the graphics screen in pixels. The maximum 
size allowed is the display's resolution in pixels (typically 640x200, but see 
XDEVICE). 

FIXED forces that dimension of its window to be the same as that dimension of the 
graphics screen. Note: the dimension being fixed must be less than the display's 
usable width/height (see XUSABLE, YUSABLE). 

MINIMUM specifies a minimum width (w) and height (h) for the window in pixels. 
MAXIMUM specifies a maximum. 

UNIT specifies the units by which the window size will be allowed to change. If 
omitted, this defaults to a single pixel. 

INFORMATION switch is ON or OFF. ON specifies that the window should have an 
information line (see WINDOW INFORMATION). 

The SCREEN command clears the graphics screen (and window) and resets the 
screen attributes (size of shorter side = 5000 user coordinates; size of longer side is 
larger in proportion; origin = bottom left corner of graphics screen; graphics style 
and text styles set to default). As far as possible, the window's current size and 
position are left unchanged. If the window is open, it is made the top window. 



Changing user coordinates 

User coordinates are used in all graphics commands for positioning and 
dimensioning within a (graphics) virtual screen. The relationship between pixels and 
user coordinates can be determined using: 

result = XPIXEL/X#s(ream) ] 
result = YPIXEL [(.^stream)] 

result is the number of user coordinates per pixel in the appropriate dimension. 

When a graphics virtual screen is set up (on entering BASIC 2 or using SCREEN 
GRAPHICS), its user coordinates are automatically defined so that graphics will be 
correctly proportioned when displayed, correcting for any asymmetry in its pixels. 
This is done by treating the screen as a rectangle, whose shorter edge is 5000 user 
coordinates long and longer edge is somewhat more than 5000 user coordinates, in 
proportion to its displayed size. A typical maximum sized screen is 5000 user 
coordinates high and approximately 8000 user coordinates wide. 

At the same time, the origin used for user coordinates is set to the bottom left 
corner of the screen. 

While this will be entirely satisfactory for most graphics output, you can redefine the 
size of user coordinates (scaling) and the origin used in a screen, as follows. 

Changing scaling 

To change the size of user coordinates, use the command USER SPACE: 

USER [# stream,] SPACE width, height 

This defines the dimensions of the graphics screen, as width user coordinates wide. 
height user coordinates high and resets the origin to the bottom left comet of the 
graphics screen. These dimensions must be greater than or equal to the width and 
height (in pixels) of the graphics screen, defined using SCREEN GRAPHICS. 

Note that USER SPACE does not actually change the graphics screen's width or 
height. Nor does it alter the units used for positioning and measurements on the 
actual display (for example, when defining a graphics screen or placing a window), 
as these use pixels, not user coordinates. 

If you want to keep a symmetrically scaled display, leave most of the work to 
BASIC 2. by specifying just one dimension in the USER SPACE command: 

USER (#stream,] SPACE dimension 

This sets the user coordinates for the shorter axis to dimension and adjusts the user 
coordinates for the other axis to produce an aspect ratio of 1:1, automatically. 

For example, suppose you had defined a graphics screen using: 

SCREEN GRAPHICS 300, 100 

and the screen pixels were approximately 3 times taller than wide, when the screen 
is displayed full size, it would look approximately square. 

(To calculate the aspect ratio of a pixel, use (YMETRES/YDEV1CE)/(XMETRES/ 
XDEV1CE). See below.) 
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You might choose to use the screen as a square of 10000 by 10000 user coordinates: 

USER SPACE 10000/ 10000 

but the graphics would then be slightly distorted. 

You can find out how distorted the display is by using the function YASPECT: 
result = YASPECT [(^stream) ] 

result is (user coordinate height)/(user coordinate width). If the display is 
symmetrical, result will be 1. 

To produce a screen of approximately 10000 by 10000 user coordinates, which does 
not distort graphics: 

USER SPACE 10000 

Another thing you may want to do is produce graphics output which is not just 
correctly proportioned, but to a particular scale, such as ten user coordinates to a 
millimetre. 

To achieve this, you first need to know the displayed size of each pixel. The 
functions XDEVICE and YDEVICE tell you the display area's size in pixels. 

To determine the display size in metres, use: 

width = XMETRES/(#sfream) ] 
height = YMETRES [<#stream) ] 

A pixel’s dimensions (in millimetres) can thus be calculated as: 

pixel-width = 1000*XMETRES/XDEVICE 
pixel-height = 1000*YMETRES/YDEVICE 

If the graphics screen had been defined as 'gwidth' by 'gheight' (pixels), its 
dimensions in millimetres would be: 

screen-width = gwidth*pixel_width 
screen-height = gheight*pixel_height 

Since you want a scale of 10 user coordinates to a millimetre, you want to define the 
USER SPACE as 10 times the screen size in millimetres: 

USER SPACE 10*screen_width, 10*screen_height 

Note that this will also correct any display asymmetry, regardless of previous use of 
USER SPACE for this graphics screen. 

Changing the graphics origin 

The graphics origin is initially defined as at the bottom left corner of the graphics 
screen. Note that this is not necessarily the bottom left corner of the window or 
display. 

The graphics origin for a particular screen can be redefined using USER ORIGIN: 
USER [^stream,] ORIGIN x;y 

x and y specify the new origin, relative to the bottom left corner of the graphics 
screen, in user coordinates. This has no effect on output already in that screen but 
will effectively shift any subsequent output. 




After moving the origin, points to its left or lower down the screen must be referred 
to using negative coordinates: 



The origin is reset to the bottom left comer when the graphics screen (SCREEN 
GRAPHICS) or user coordinates (USER SPACE) are redefined. 

Using the mouse 

Programs can read the position of the mouse pointer on the screen (in screen pixels) 
and detect whether mouse buttons are being pressed, using the functions XMOUSE. 
YMOUSE and BUTTON, as described in the chapter on input. 

The appearance of the mouse pointer can be changed, using: 

WINDOW [#stream] MOUSE mouse-form 

mouse-form is an integer, specifying the form the mouse pointer should take while 
it is in that stream's window and that window is the top window. (See the 
appendices for details.) 


Summary of functions 


The following functions, introduced in this chapter, can be used to check device, 
virtual screen and window details: 


Device dimensions 

=XDEVICE, =YDEVICE 
=XUS ABLE, = YUS ABLE 
=XMETRES, =YMETRES 

Device scaling 

=XPIXEL, =YPIXEL 
=Y ASPECT 


device dimensions in pixels 

usable device area dimensions in pixels 

device dimensions in metres 

pixel size in user coordinates 
aspect ratio of user coordinate points 


Virtual screen dimensions 

=XVIRTUAL, =YVIRTUAL graphics screen size in user coordinates, text screen 

size in columns and lines 
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Windows 

=XWINDOW, =YWINDOW 
=XACTUAL, =YACTUAL 
=XPLACE, =YPLACE 
=XSCROLL, =YSCROLL 


window size (usable) in pixels 

window size (overall) in pixels 

position of window on display in pixels 

position of window in its screen in user coordinates 

(graphics screen) or columns and lines (text screen) 


Using other devices 

As well as the display and system printer, text can be output to other suitable 
devices, such as dot matrix or daisywheel printers. To use such a device, you must 
first open it for output, using: 

OPEN #stream PRINT device-number 

Graphics can also be output to suitable 'graphics devices', such as plotters or bit 
image printers. 

To use a graphics device, you must first open it for output, using: 

OPEN #stream DEVICE device-number 

device-number is an integer expression specifying the device number. The device 
numbers used within a GEM system (not all of which are suitable for text or 


graphics 

output) are: 

Device 

Device 

number 

description 

1 - 10 

screens 

11 - 20 

plotters 

21 - 30 

printers 

31 - 40 

metafiles 

41 - 50 

camera 

51-60 

tablet 


A device may only be open on one stream at a time. To assign it to a different 
stream, close its present stream first: 

CLOSE #stream 

(If there are graphics commands stored for this device, they will be output and a 
paper advance executed, first.) 

Depending on the device, graphics output may not be acted upon until the 
command: 

GRAPHICS [^stream,] UPDATE /NEW; 

The effect of NEW depends on the device. For example, on a bit-image printer or 
drum plotter, it will advance the paper at the end of the output. Refer to the guide(s) 
supplied with the device for details. 

Limitations 

Devices other than the display will not provide windowing or graphics screens so 
that the whole device area will always be 'visible' and available for output. 

in 



Hardcopy devices are unlikely to provide any erasing facilities, so that commands 
such as CLS will not work, and operations that involve changing the colours of 
existing output may be limited to what can be achieved by 'overprinting' (for 
example, lightly coloured output written over existing darker output will not be 
visible). 

Summary of facilities 

Text output devices can be used just like printers, as described in Chapter 5. 

The main commands and functions (identified by a preceding '=') that can be used 
on graphics output devices are as follows. These can be used as described in this 
and the previous chapter, with the exception that references to 'graphics screen’ or 
'window' should be interpreted as 'usable device area'. 

Streams 

OPEN DEVICE 
CLOSE 

Device size and resolution 

=XDEVICE, =YDEVICE 
=XUSABLE, =YUSABLE 
=XMETRES, =YMETRES 

Units and positioning 

USER SPACE 
USER ORIGIN 
=YASPECT 
=XCELL, =YCELL 
=XPIXEL, =YPIXEL 
=EXTENT 

Graphics output 

PLOT 

LINE 

BOX 

SHAPE 

CIRCLE 

PIE 

ELLIPSE 
ELLIPTICAL PIE 

GRAPHICS (COLOUR, LINE, etc) 

Turtle graphics 

LEFT 

RIGHT 

POINT 

/move; forward 

=HEADING 
=TOWARD 
=DISTANCE 
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Text output 


PRINT, AT, TAB. COLOUR t, EFFECTS+. FONTt, POINTS t. 
ANGLE t, MODEt. MARGIN t, ADJUST t 
SET (COLOUR t. EFFECTS t. etc) 

MOVE 
LOCATE 
=FONT$ t 
=POINTSIZE t 
=XPOS, =YPOS 
=POS, =VPOS 
=EXTENT t 


t these facilities may or may not be available, depending on the device and device 
driver used. 




7 . PROGRAM STRUCTURE AND CONTROL 


In simple programs, each instruction is executed exactly once, in the same order as 
in the program. This type of program is very simple to write and understand, but not 
ideal for most tasks. BASIC 2 provides facilities to make programs more versatile, 
giving you control of the order in which instructions are obeyed and the number of 
times they are obeyed. 

These are the 'control' class of keywords. They provide three types of facility: 

- altering the order in which instructions are obeyed ('sequence') 

- choosing between alternative instructions ('selection') 

- repeating instructions or groups of instructions ('repetition') 

As tasks grow bigger and more complex, so too do the programs needed to perform 
them. A fourth class of keywords is used to help you 'organise' complex programs, 
to make them easier to design, understand, and maintain. These will be described 
as the 'structure' keywords. 

Each class will now be discussed in turn, in the following order: 

- sequence 

- structure 

- selection 

- repetition 


Sequence 

Program lines are normally obeyed strictly in their order in the program, with 
statements in a multi-statement line being obeyed from left to right. Facilities 
described here allow you to alter this sequence in a fixed manner and make the 
program stop where you want rather than after the last line. 

Order of execution 

To change the order of execution unconditionally, use the command GOTO: 

GOTO location 

location must be a line-number or a label. When the GOTO statement is obeyed, 
execution will continue at the specified destination. 

A line-number is any decimal integer constant in the range 1 to 65535. that has 
been used to start a program line: 

line-number statement [: statement...] 

For example: 

1234 total = total+1: PRINT "Cars to date =";cars 
A label is a name, declared as a label by a LABEL statement: 

LABEL label [: statement...] 
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For example: • 

LABEL adcLcar: total = total+1: PRINT "Cars to date =";cars 

label can be any simple numeric variable name (ie without array or record 
extensions). A label is not a variable, so it cannot be PRINTed, used in expressions, 
assigned to, etc. 

The location specified is found by searching from the start of the program for the 
first matching location. If no matching location is found, an error results. 

You may. if you wish, use the same line-number for different lines in the program, 
but only the first will be found. 

location may be the GOTO line, before or after it. If it is ahead of the GOTO line, the 
intervening lines are skipped over as if they did not exist. This is mainly used to 
skip over a part of a program that you don't want to use at the moment, for example 
while developing a program. 

If location is before or is the GOTO line, a 'loop' is produced. This is described in 
the section on repetition, later in this chapter. 

GOTO becomes more useful when used with the decision-making facilities, 
described below. (It is really a 'leftover' from earlier versions of BASIC, retained for 
compatibility.) 

Stopping execution 

Left to its own devices, a program only stops when the last program line has been 
executed or the user presses Ctrl-C. 

There are two commands that stop the program when executed: END and STOP. 

END stops the program just like it stops when it nans out of program lines. END is 
mainly used to stop the program when it has finished its intended tasks but there 
are more lines in the program. 

STOP stops the program and displays a message to that effect. STOP is mainly used 
to 'breakpoint' a program while testing it. in conjunction with the command CONT 
which will cause the program to resume execution from the next instruction. (This 
technique is described in greater detail in Part IV.) 

Structuring programs 

To simplify writing complex programs, most programmers choose to split the task 
into sub-tasks and solve each sub-task using a distinct part of the program or 
'module'. This technique is known as 'decomposition' - a sort of divide and 
conquer! 

These modules, being smaller and simpler, are easier to design, write and test. The 
final program is made by combining individually tested modules, so that final 
checking mainly consists of making sure that they work together as intended. 

There are other advantages to structuring a program into modules, including making 
the program easier to understand or change, reducing the size of the program (by 
using the same module in several parts of the program) and even saving 
programming by re-using the same module in different programs. 




This section describes how to structure a program in this way, using ‘layout 
facilities’, 'subroutines', and 'functions'. 

Program layout 

As soon as a program grows beyond about 10 lines or starts to use complex 
instructions which are difficult to understand, its workings will no longer be obvious 
to someone trying to understand, correct or change it. This may not seem very 
important, but remember, this could be you in six months' time! 

The simplest way to make a program easier to understand is to break it into smaller 
chunks and simply label each chunk with what it does, as follows. 

To do this, decide what logical stages the task consists of ('decomposition') and put 
all the instructions to complete each stage together. Separate each stage with a 
program line consisting of just ' (this is a convenient abbreviation for REM). 

This will produce a program which will display as visually distinct stages. You can 
also use spaces at the beginning of program lines to indent statements as required. 

To indicate what a particular stage in the program does, use REM. This command 
simply makes BASIC 2 ignore the rest of the line! It is used to insert comments 
(remarks), usually to explain what is going on. Another important aid to 
comprehension is to use variable names that indicate their role. 

Contrast the following two versions of the 'same' program: 

a$ = "Markup program" 
a = 0.5 

PRINT a$:PRINT 
INPUT "Product price";b 
INPUT "Product name";b$ 
c = b*(1+a) 
d = 0.15 

INPUT "How many";e 
f = e*c*(1+d) 

PRINT "Your total stock of ";b$;" should sell for ";f 
END 

The only way to guess what is going on in this first version is by examining the 
prompts or running the program. This is a rather extreme example of bad variable 
naming and sequencing. 

REM ** set up variables and screen ** 
vat = 0.15 
markup =0.50 
titleS = "Markup program" 

I 

REM ** set up screen ** 

PRINT titleS: PRINT 

i 

REM ** get input ** 

INPUT "Product price";price 
INPUT "Product name";nameS 
INPUT "How many";number 

I 
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REM ** calculate value including vat and markup ** 
markup-price = price*(1+markup) 
value = markup_price*(1+vat) 

i 

REM ** display value ** 

PRINT "Your total stock of ";name$;" should sell for ";value 
END 

The second version is, by contrast, far easier to understand and to check. Sensible 
stages have been chosen which are clearly labelled (with REM) and the variables 
indicate what they are used for. The advantages become obvious when you try to 
work on or check these programs. For example, is there a value assigned to 'vat' ('d' 
in first program) before using it? In the first version, you have to hunt for an answer; 
in the second, all constants are assigned to pseudo-constants in one place, making 
it easy to check. 

The second version is however rather longer, which means that it would take longer 
to type and would be a little more difficult to examine on the screen. (It is. in truth, 
somewhat over-documented for such a small program, to emphasize the point!) 

Programs can be more obviously and conveniently segmented by using subroutines, 
and functions, as described below. 

Subroutines 

A subroutine is a sequence of program lines which can be used ('called') from 
anywhere in the program by executing a single command. This command is 
GOSUB, which is followed by a location specifying the start of the subroutine: 

GOSUB location 

location is a line-number or label, as described above, for GOTO. 

When this instruction is obeyed, execution continues from the line specified, just 
like GOTO. However, BASIC 2 remembers where in the program the GOSUB 
instruction was, and returns to the next instruction after that when it executes the 
command RETURN. 

A subroutine thus consists of a sequence of program lines, ending with the 
command RETURN. The start of a subroutine is not fixed in the subroutine, but is 
determined by the location in the GOSUB instruction that enters it. Thus, you can 
enter the 'same' subroutine at a variety of different points. 

There is no limit on the number of subroutines allowed in a program. Subroutines 
may also call other subroutines (ie they may be 'nested'), to any depth. The only 
limit is the usual one of memory size. 

Subroutines should be kept away from the main part of the program to make sure 
that they are only executed by GOSUB instructions. The best place is usually at the 
end of the program, after an END instruction. If a RETURN command is executed 
without a GOSUB instruction (ie n GOSUBs have been executed and an n+fth 
RETURN is executed), an error results. 

Subroutines are used for two main reasons: 

- to structure a program, into modules 

- to reduce the size of a program 




Subroutines as modules 

To structure a program into modules, you can design each component task as a 
subroutine and make the core of the program (sometimes called its 'root') a series of 
calls to these subroutines ie GOSUB statements. This makes it very simple to 
understand the general flow of the program, especially if the calls are documented 
(using REM statements) and/or made to labels: 

GOSUB setup 
LABEL root loop 
GOSUB choose 
GOSUB actionchoice 
GOTO root loop 
GOSUB finishup 
END 

REM *** SUBROUTINES *** 

LABEL setup 
subroutine 
RETURN 

LABEL choose 

subroutine 
etc,etc 

Since subroutines can be ‘nested’, this technique of ’decomposition’ can be carried 
a stage further, programming each subroutine as calls to subsidiary subroutine: 

LABEL setup 
GOSUB infile 
GOSUB pseudoconstants 

etc 

RETURN 

LABEL choose 
GOSUB convert 
GOSUB act 
option = 2 
RETURN 
etc,etc 

Using decomposition, you can also break down each stage to its constituent 
substages until each substage is of a manageable size and complexity (say, about 10 
instructions each). For example, a program to print an order might break down as: 

Task: print an order 


prepare process orders tidy up 


||| | print formfeed 

set up variables loop get order print order 


construct text 


set up printer 


get name 


get amount 


check space 


—i 

print text 











Each level in this hierarchy could be a subroutine. 

By segmenting the program in this way, you can make the structure of the program 
reflect the structure of the task. This will make it easier to design and understand. It 
also allows you to write the program a bit at a time. Starting from the top, you write 
only one level down at a time, checking that each level works correctly before 
proceeding to the greater detail of the next level. This makes it easier to spot and 
correct errors, because you will always know the level they have developed on. 

Subroutines for economy 

When analysing a task, you will often find that the same or similar sub-task crops 
up at several stages. Rather than program each as a separate stage or module, you 
can write a single subroutine to satisfy them all. then simply call it (using GOSUB) at 
the appropriate points in the program. 

For example, you might want to clear the window and display a message 
surrounded by asterisks, in several places in a program. If the message is the same 
in each place, just include it in the subroutine: 

GOSUB title 

GOSUB title 

LABEL title 
CLS 

PRINT "***ANALYSIS PROGRAM***" 

RETURN 

If the message is different each time, use a variable in the subroutine and assign the 
new message to it each time before calling the subroutine: 

messages = "ANALYSIS PROGRAM" 

GOSUB title 

messages = "RESULTS" 

GOSUB title 
etc 

messages = "PLEASE WAIT" 

GOSUB title 

LABEL title 
CLS 

PRINT "***";messages;"***" 

RETURN 

Using subroutines like this doesn't just help you write more compact programs. It 
can also make programs easier to change and correct, when the changes are 
required to shared commands in a single subroutine, rather than several occurrences 
of duplicated commands throughout the program. 

Functions 

There are a wide range of built-in functions such as MAX, STR$, CINT etc that 
process information to produce a single numeric or string results. 
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You may also define your own functions for use within the same program. These 
functions are sometimes called 'user-defined functions’ to distinguish them from the 
supplied 'built-in functions', but within this section, they will just be called 
'functions’, for brevity! 

A function is defined using DEF FN, as a single instruction: 

DEF FHname [(formal-parameters) ] = expression 

name can be any simple variable name, with type corresponding to the type 
returned by the function. 

formal-parameters are value parameters, local to the function, expression is an 
expression which is evaluated to yield the result returned. This may or may not use 
the formal-parameters. 

The function definition must be executed before the function can be used. 

A function is used by including it as an information item in a command, for 
example: 

PRINT FN name [(actual-parameters) ] 

The actual-parameters must match the formal-parameters. There must be the same 
number of actual-parameters as formal-parameters , separated by commas, with 
each actual-parameter having a type that is compatible with the corresponding 
formal-parameter. 

Selection 


Decision-making is the vital spark that stops a computer program working 
'mechanically' like a calculator and starts it working 'intelligently'. 

In programs, the choices made are between obeying and not obeying certain 
instructions, called 'dependent instructions’. Decisions rest on the values of crucial 
items of information, tested in decision-making structures. They are: 

• IF THEN ELSE: obey one group of instructions or the other, depending on the 
relationship between two expressions 

• ON GOTO/GOSUB: choose between a number of destinations/subroutines 
depending on a numeric expression 

Except where stated otherwise below, you are free to use any of these types of 
structure in any combination, anywhere in a program. 

IF statements 

IF is used to start a variety of decision-making structures, using the keywords IF. 
THEN, and ELSE. These all evaluate a condition to 'true' or 'false', to decide which 
of the subsequent statements are executed. 

Simple decisions using IF 

The simplest form is: 

IF relational-expression THEN true-statements 
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relational-expression states a relationship between two compatible expressions, 
using the relational operators '>' (is greater than), '<’ (is less than) and '=' (is equal 
to) ie: 

expression relational-operator expression 

If the relationship stated in the relational-expression is found to be true, all the 
instructions after THEN on that line are obeyed, otherwise execution continues on 
the next line. For example, with: 

IF count<10 THEN PRINT "Less than 10!":INPUT "New value";count 

the print and input statements will only be executed if countclO ie if the variable 
‘count’ has a value less than 10. 

Note that 'IF relational-expression THEN statement' is treated as a single statement 
ie there is no need for a colon as statement separator after THEN. 

To obey a different group of statements if relational-expression is not true, include 
the keyword ELSE: 

IF relational-expression THEN true-statements ELSE lalse-statements 

true-statements will only be obeyed if relational-expression is true, false-statements 
only if not true. In either case, execution will normally continue on the following 
line. 

The above IF statements control execution of statements up to the end of the line. 

Conditions 

As described above, the IF statement uses a condition. A condition can be: 

a relational-expression 
a logical-expression 
a numeric-expression 

Relational expressions 

A relational expression is a statement of the relationship between two expressions, 
made using the 'relational operators', '>’, '=' and '<’. It is defined as: 

expression relational-operator expression 

where the relational-operators are as follows: 


Expression Result 


a 

< b 

true 

if 

a 

is 

a 

<= b 

true 

if 

a 

is 

a 

=< b 

true 

if 

a 

is 

a 

= b 

true 

if 

a 

is 

a 

<> b 

true 

if 

a 

is 

a 

=> b 

true 

if 

a 

is 

a 

>= b 

true 

if 

a 

is 

a 

> b 

true 

if 

a 

is 


less than b 

less than or equal to b 
less than or equal to b 
equal to b 
not equal to b 
greater than or equal to b 
greater than or equal to b 
greater than b 


Typical relational expressions are: 

count1 < count2 

name$ - IIM 

key <> pointer%*2+1 






The two expressions being compared must be of compatible types, ie must both be 
numeric or both be string. Relational operators have a lower precedence than any of 
the numeric or string operators, so there is no need to place brackets around the 
expressions being compared. 

String expressions are compared by comparing the internal codes of characters in 
the same positions in each string, starting from the first character. As soon as there 
is any difference, this is the result and the comparison ends. If both strings run out 
at the same time and no difference has been detected, they are equal. For example, 

"AA" is less than "AB", because "A" and "B" have codes 64 and 65. (All the 
characters and their codes are listed in Appendix I). The end of a string can be 
considered as having the code -1, so that "AA" is greater than “A", because the 
"second character" of the second string has a code of -1. 

Numeric expressions are compared more simply, with smaller (more negative) 
numbers being less than larger (more positive numbers). Take care, however, when 
comparing for equality numbers with fractional parts, as minor differences in the nth 
decimal place may result from the number system used, so that numbers which look 
equal may not be equal. If either expression might have a fractional part, its is best 
to round it explicitly. For example, instead of: 

IF remainder = 0 THEN PRINT "divides exactly" 

use: 

IF ROUND(remainder,7) = 0 THEN PRINT "divides exactly" 

or even: 

IF ABS( remainder) < 0.0000001 THEN PRINT "divides exactly" 

Logical expressions 

A logical-expression is an expression combining numeric-expressions, relational- 
expressions and/or other logical-expressions, using the logical (or binary) 
operators, NOT, AND, OR and XOR. When used with relational-expressions, the 
logical operators function as follows. (Use with numeric-expressions is described in 
the chapter on numeric processing.) 

NOT NOT is used to invert the sense of a logical expression, so if 'a > 6‘ evaluates to 
‘true’, 'NOT (a > 6)' will evaluate to 'false'. 

AND The result of combining two relational-expressions with AND is 'true' only if both 
are 'true'. Thus, the result of '(1 = 2) AND (3 = 3)' is 'false' because while the 
second expression is 'true', the first is ‘false’. 

OR The result of combining two relational-expressions with OR is 'true' if either (or 
both) are 'true'. Thus, the result of '(1 = 2) OR (3 = 3)' is 'true' because while the 
first expression is 'false', the second is 'true'. 

XOR The result of combining two relational-expressions with XOR is ‘true’ if exactly one 
of them is 'true'. Thus, the result of ‘(1 = 2) XOR (3 = 3)’ is 'true' because while the 
first expression is 'false', the second is 'true'. 

The order of precedence of operators in a logical-expression is NOT (highest), then 
numeric/string, then relational, then AND, OR and XOR. If in doubt, use brackets! 

Numeric expressions 

The third type of condition is a numeric-expression. This is evaluated and 
considered to be 'false' if 0, otherwise ‘true’. This allows you. for instance, to use 
variables as 'switches’ in IF statements, controlling execution by assigning values to 
these variables elsewhere. 
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In this context, it is useful to know that a relational-expression actually evaluates to 
a numeric result: of -1 if true, 0 if false. Pre-defined constants are supplied with 
these values for your convenience, named TRUE and FALSE. 

By using numeric variables as conditions, you can, for example, simplify IF 
statements by coding complex logical-expressions just once and assigning the 
result to a meaningful variable name, which is then used throughout the program. 
For example: 

retired = (age >= 65) OR (age >=60 AND sexS ="F") 
wealthy = (saved > 5000) OR (assets > 30000) 

IF retired THEN plan(gross) 

IF retired AND wealthy THEN PRINT "Buy gold!!!" 
etc. etc 

(You can also use switches to effectively alter the test being applied in IF 
statements, by assigning different logical-expressions to the switch in different 
paths through the program.) 

Multiple IF statements 

To simplify programming 'branching' logic, IF statements can be nested ie can 
themselves be used as true-instructions or false-instructions. 

These behave much as you would expect, so an ELSE clause is taken as the 
alternative to the most recent THEN clause. 


ON GOTO/GOSUB 

The ON keyword can also be used to branch to one of a number of destinations, or 
select one of a number of subroutine or procedures, based on the value of a numeric 
expression, as follows. 

ON numeric-expression GOTO location,location,location... 

numeric-expression is evaluated when the instruction is executed to yield an 
integer, n. If there is an nth location in the list, execution continues from that. 
Otherwise, the whole instruction is skipped, without error. 

Similarly: 

ON numeric-expression GOSUB location,location,location... 
where location is a line number, label or subroutine name. 



Repetition 


Many of the tasks that you program will involve repetition of similar or even 
identical steps. This section will describe how to code such repetition easily and 
efficiently. 

Instructions are repeated by including them in structures called 'loops'. A loop has 
three main properties: 

- a start 

- an end 

- an exit mechanism 

Loops can be constructed using commands described already (GOTO and IF THEN 
ELSE), but there are three pre-defined looping structures which are far superior for 
most purposes: 

Loop name Action 

FOR loop loop a given number of times 

WHILE loop loop only while a condition is true 
REPEAT loop loop until a condition becomes true 

Each type of loop is particularly suited to its own type of repetitive task. They will 
now be described in turn. 

FOR loops 

The FOR loop starts with a FOR statement and ends with a NEXT statement: 

FOR control-variable - start TO end /STEP step] 
loop-body 

NEXT [control-variables] 

control-variable is a simple numeric variable (ie not an array element nor a record 
field), start, end and step are numeric expressions. 

To improve legibility, it is usual to indent the loop-body by typing leading spaces, 
as shown, although this is not necessary. 

The FOR loop is entered by executing the FOR instruction. Ignoring the optional 
STEP keyword for the moment, the loop is executed as follows: 

1 control-variable is set to start and end is evaluated and stored 

2 If control-variable is greater than the stored end, the FOR loop finishes immediately, 
with execution continuing from the instruction after the NEXT 

3 Instructions in the loop-body are obeyed as normal 

4 When NEXT is executed, control-variable is incremented by 1. then execution 
continues from step (2) 
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control-variable can be used by instructions within the loop-body, or even changed 
by them, but this is not recommended. When the loop finishes its value is 
preserved. 

start and end are evaluated when the FOR instruction is executed; changing 
variables used in either of these while in loop-body will have no effect on looping. 

The FOR loop can also be left by jumping past the NEXT instruction, or by using a 
RETURN instruction, if the loop is inside a subroutine, procedure or function. (Rather 
than use this you might prefer to use a WHILE or REPEAT loop, as described 
below.) 

The optional STEP keyword is used to specify an increment (other than the default 
of +1) for use in step (4). step may be positive or negative; if negative, the 
comparison with end in step (2) changes sense (re the loop terminates when 
control-variable is less than the stored end). 

If specified, the optional control-variable on the NEXT instruction is checked 
against the control-variable for the current loop. If it is not the same, an error is 
generated. 

The FOR loop is most useful when the number of times the loop should be executed 
is known at the start of the loop. For example, when calculating a 'times table’, or 
processing each element of an array in turn. 

The loop-body can include most instructions, including other FOR loops ie FOR 
loops can be nested. Nested FOR loops should use different control variables. 

A NEXT instruction can be used to end nested FOR loops, by listing the 
control-variables after it, separated by commas. These should be in the order 
’newest FOR loop’ ... ’oldest FOR loop’. 

NEXT [control-variable] [,[control-variable]...] 

Any or all of these control variables can be simply omitted if you do not want to 
specify them. For example: 

FOR x = 1 TO 10 
FOR y = 1 TO 10 
FOR z = 1 TO 10 

cells<x,y,z> = RND(100) 

NEXT z,y,x 

The last line could be replaced by: 

NEXT z,y, 
or NEXT „ 

etc.etc 

WHILE and REPEAT loops 

The FOR loop is ideally suited to repetition where the number of repetitions required 
can be calculated at the start of the loop. As this will not always be the case, 
BASIC 2 provides two other types of loop, in which looping is controlled by a test! 
made at the start or end of each repetition. 

These loops are suited to situation- 'here the number of times a loop should be 
executed is not known when it is started. All the programmer has to do is make 
sure that the test controlling the loop will change to make the loop finish, when 
appropriate. 



The first such loop is the WHILE loop, which is repeated while a condition is true: 

WHILE condition 
loop-body 

WEND 

condition is a relational-expression, logical-expression or numeric-expression, as 
described previously, for IF statements. 

This loop is entered by executing the WHILE instruction. The loop is then executed 
as follows: 

1 condition is evaluated. If false (0), the loop ends and execution continues with the 
instruction after WEND. Otherwise (not 0): 

2 Instructions in loop-body are obeyed as normal 

3 When WEND is executed, processing continues from step 1 

loop-body can include most instructions, including other WHILE loops ie WHILE 
loops can be nested. 

A WHILE loop can be left through its WHILE instruction, by using GOTO to jump 
past the WEND, or by executing a RETURN (if the loop is within a subroutine, 
procedure or function). 

A WHILE loop must have only one WEND. 

The REPEAT loop is very similiar to the WHILE loop, also controlling looping 
through the use of a condition. It takes the form: 

REPEAT 

loop-body 
UNTIL condition 

condition is a relational-expression, logical-expression or numeric-expression, as 
described previously, for IF statements. 

This loop is entered by executing the REPEAT instruction. The loop is then 
executed as follows: 

1 Instructions in loop-body are obeyed as normal 

2 When UNTIL is executed, condition is evaluated. If true (not 0), the loop ends and 
execution continues with the next instruction. Otherwise (if 0). execution continues 
from step 1 

loop-body can include most instructions, including other REPEAT loops ie REPEAT 
loops can be nested. 

Note that the loop-body of a REPEAT loop will always be executed at least once, 
unlike the body of a WHILE loop. 

A REPEAT locp must have only one UNTIL statement. It can be left via the UNTIL 
statement, jumping out of the loop (GOTO) or executing a RETURN (if the loop is 
within a subroutine or function). 
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Choosing a loop 

Any of the three types of loop can be made to resemble any other type, but this is 
pointless. The choice of loop type should be largely determined by the logic of the 
repeated task being programmed. 

In general, if the number of iterations can be calculated when the loop is entered, 
with no exceptions, then use a FOR loop. 

If the number of iterations is not entirely predictable on entry, use a WHILE or 
REPEAT loop, even if this means maintaining a counter to step through arrays etc. 

In choosing between REPEAT and WHILE loops, while you should try to use 
whichever most closely resembles the logic of the task being programmed, the 
choice is really largely a matter of personal preference. The main difference is that a 
REPEAT loop will always be executed at least once. 

A REPEAT loop is better when the body of the loop is needed to set up the 
condition. A WHILE loop is better when the condition is already set up on entry and 
may already be false. 

For example, to code 'scan the keyboard until a key is pressed and return it', a 
REPEAT loop is ideal: 

REPEAT 

pressed* = INKEYS 
UNTIL pressed* <> "" 

A WHILE loop can be used, but is not quite so clear or concise: 

pressed* = INKEYS 
WHILE pressed* <> "" 
pressed* = INKEY* 

WEND 

To code 'print characters from text* until you reach an asterisk', you would probably 
use REPEAT. But to code 'keep printing characters from the string while they are 
not asterisks’ you would probably use WHILE. In fact, the two specifications require 
exactly the same processing. 

Using a REPEAT loop, you might write: 

point = 1 
REPEAT 

PRINT text*{point> 
point = point+1 
UNTIL text*{point>="*" 

Using a WHILE loop: 

point = 1 

WHILE textSlpoint><>"*" 

PRINT text*<point> 
point = point+1 
WEND 

However, the loop using REPEAT is slightly inferior, because it will not behave 
correctly if the first character of text* is an asterisk. To exactly duplicate the action 
of the WHILE loop, you would need to add a line to the start of the REPEAT loop to 
test for this and jump over the loop if true. H 




8. DISCS AND SEQUENTIAL FILES 




Discs are used to store information for later use. in the form of named objects called 
'files'. The main types of information you can store when using BASIC 2 are 
programs and information created or used by programs. 

This chapter describes the commands and other facilities that you can use to 
examine discs and the files they contain. It then describes how to write programs to 
store and retrieve information, using files. 

Naming 

A file is referred to by its 'file name’, which is: 

[drive: ][ \ ][path\ ]file 

drive is a single letter, specifying the disc drive that the file is on. If omitted, the 
current drive is assumed. 

path is a sequence of one or more directory names, separated by \ characters. The 
special directory name .. specifies the parent of the directory which precedes it 
in the path. 

path is used to specify the route to the directory containing the file, when it is not 
in the current directory. If path is preceded by a \. the route starts in the 'root* 
directory, otherwise it starts in the current directory. For example, ‘\jobs\local\ If 
omitted, the current directory on the current (or specified) drive is assumed. 

file is the name of the file as displayed when its directory is listed, which may 
include an optional .extension. For example, metal.seq. 

Note that 'hidden' and 'system' files will be invisible to BASIC 2. 

A ‘directory name' is specified as: 

[drive: J[\][path[\]] 

If null, the current directory is assumed. The terminating \ is optional, except in 
commands which may also take a file name as an argument, when it must be used 
to show that the argument is a directory, not a file. 

For further details of drives, directories, file specifiers and file naming, refer to your 
DOS user guide. 

General purpose disc commands 

BASIC 2 provides a number of facilities that can be used to examine and 
manipulate any disc files, regardless of their nature. 

In this description of general purpose disc commands, arguments are shown either 
as rest-of-line or string-expression. 

Commands shown as using rest-of-line can only be used as the last instruction in a 
program line or as a command in the Dialogue window and any output they produce 
will always be in the Dialogue window (even if used in a program). These 
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commands are really intended for use as immediate commands (ie not in programs) 
- they use the Dialogue window so as not to interfere with any program output, 
when debugging. 

Commands using a string-expression can be used anywhere and behave as normal 
BASIC 2 instructions. 

Examining files 

To display information about files, use the commands DIR or FILES: 

DIR [rest-of-line] 

FILES ftstream,] string-expression 

The argument limits the names listed. If it is a directory name (which must end with 
\), all files in that directory will be listed. If it is a file name (which may include 
wildcards: see your DOS user guide for details); all files matching that name will be 
listed. If omitted or a null string, all files in the current directory will be listed. 

FILES lists the files to the default stream or specified stream. DIR lists them to the 
Dialogue window, as described previously. 

To display the contents of a text file, use the commands TYPE or DISPLAY: 

TYPE rest-of-line 

DISPLAY [#stream,J string-expression 

The argument specifies the file's name explicitly without wildcards. Do not use 
these commands to print non-text files or directories, as unpredictable results will be 
produced. 

To search a disc for the nth file name matching a wildcard specification, use the 
function FINDS: 

result = FINDS ( string-expression[, n]) 

string-expression specifies the name of the file to be searched for, and may use 
wildcards, n is an integer expression specifying that the nth file matching the 
string-expression should be searched for. 

result is the name of the matching file, if found, or a null string, if not found. For 
example, to check if there is a file with the type 'BAS' on the disc: 

IF FIND$("*.BAS") = "" THEN PRINT "Not found" 

The name returned by FINDS is a 12-character string. For example to find the name 
of the second file in the current directory: 

file$ = FIND$<"*.*",2) 

Manipulating files 

To delete a file or files, use the commands ERASE, DEL or KILL: 

ERASE rest-of line 
DEL rest-of-line 
KILL string-expression 

The argument specifies the name of the file(s) to be erased from the disc MultiDle 
files may be deleted by using wildcards in the name. 

To change the name of a file, use the commands REN or NAME: 




REN constantl constant2 

NAME string-expressionl AS string-expression2 

This changes the name of the file named string-expressionl or constantl to 
string-expression2 or constant2. An error will result if the the file does not exist or 
a file already exists with the new name. 

Directories 

There are three directory commands, for changing the current directory, creating 
and deleting directories. 

To change the current directory, use the commands CD or CHDIR: 

CD rest-of-line 
CHDIR string-expression 

The argument specifies the new current directory. 

To create (make) a directory, use the commands MD or MKDIR: 

MD rest-of-line 
MKDIR string-expression 

The argument specifies the name of the new directory. 

To delete (remove) a directory, use the commands RD or RMDIR: 

RD rest-of-line 
RMDIR string-expression 

The argument specifies the name of the directory to delete. 

To find the name of the current directory, use the function CHDIRS: 
result = CHDIRS ( string-expression) 

The first character of string-expression specifies the drive whose current directory 
should be returned. The parameter (together with its brackets) can be omitted; if so 
the current directory on the current drive will be returned. 

To search the current drive for the nth directory whose name matches a wildcard 
specification, use the function FINDDIRS; 

result = FINDDIRS ( string-expression[, n)) 

string-expression specifies the name of the directories to be searched for. using 
wildcards, n is an integer expression specifying that the nth directory matching the 
string-expression should be searched for. 

result is the name of the matching directory, if found, or a null string, if not found. 
DRIVE string-expression 

Sets the default drive to that specified by the first letter of the string-expression. 

Storing information on discs 

Discs can be used not only to store programs, but to store information produced 
by and for use by programs. Using this facility, tasks that involve storage of large 
amounts of changing information become practical, such as keeping personnel 
records, stock lists, address books, etc. 
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A program stores information on discs by writing it to named files, which we will 
call 'data files'. The advantages and disadvantages of storing information in data 
files rather than variables include 


Files 

Information preserved until deliberately 
erased or file deleted 

Limited by disc capacity, which is 
normally greater (much greater, in the 
case of a Winchester disc) 

Information easily shared between 
programs 

Access time varies between nearly 
instantaneous and several seconds 

Information must be transferred to 
variables before it can be used in 
instructions 


Variables 

Information easily lost, eg when the 
computer is turned off 

Limited by computer memory 


Information cannot be shared between 
programs 

Nearly instantaneous access 


Information can be used directly in 
instructions 


To summarise, data files provide a way of preserving information so it can be easily 
used later with the same program or different programs, but take a little more effort 
and time to use than variables. 


A sequential file is used rather like a DATA statement, containing information items 
which must be read back in the same order as they were written to the file. 

A random file is used rather like a single-dimensional array, with each item having a 
number. Information can be read from it in any order, by specifying the number of 
the items required 

A keyed file is like a random file, but allows you to choose items much more 
conveniently, using 'keys’ such as a surname or stock description, that have been 
defined for that item. 

Sequential files are the simplest to use and will be described in this rest of this 
chapter. Random files and keyed files will be described in later chapters. 

Opening a file 

Before you can write to or read from a sequential file, you must "open' a stream to it. 
using the keyword OPEN: 

OPEN #stream (qualifier] mode file-name 

stream is an integer expression in the range 0-15, which you will use in all 
subsequent instructions to refer to this file, streams 0 - 2 are usually used for 
output to the printer and screen windows, so you will usually use streams 3-15 
for access to disc files, stream must not already be in use for any other file or output 
destination (screen, printer, graphics device, etc). 

file-name is a string expression specifying the name to use for the file. 

mode is a keyword, indicating the type of output device and way it will be used 



For sequential files, the keywords are: 

INPUT - read a file 
OUTPUT - create a file 
APPEND - add to the end of an existing file 

If opening a file for INPUT, the file must already exist or an error will result. 

Normally, when opening a file for OUTPUT, any file with that name will be deleted. 
Similarly, when opening a file with APPEND mode, it will be added to if it exists, or 
created if it does not. 

However, the optional qualifier can be used with OUTPUT or APPEND, to alter this, 
as follows 

NEW - the file must not exist already and is created 
OLD - the file must exist already 

The most useful combinations of qualifier and mode are: 

NEW OUTPUT - to ensure that the file created does not already exist 
OLD APPEND - to ensure that the file being added to does already exist 

Note that you can also use the function FINDS to check for the existence of a file 
before opening it. 

If you run out of streams (which is unlikely!), you will have to close one of those 
that is already open (see CLOSE below). 

A file stays open until you CLOSE it (as follows). You should not remove a disc 
containing an open file until it has been closed (or output may be lost). 

Closing a file 

When you have finished reading or writing a file, close it using the command 
CLOSE This: 

- ensures that all information written to the file (if opened for output/appending) 
has actually been transferred to it 

- allows the file to be opened again 

- frees that stream for re-use 

Files are closed with the command CLOSE: 

CLOSE 

or CLOSE #stream[ f if stream...] 

The first form closes all disc files that are open. 

The second form is used to close specified streams. For example: 

CLOSE #6, #client_file, #stockfile 
Open files are also closed automatically on exit from BASIC 2 
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Creating a file 

A sequential file is created in three stages: 

- opening the file 

- writing information to the file 

- closing the file 

Opening files and closing files have already been described. 

Once the file has been opened for output, you can write information to it using the 
command PRINT # stream: 

PRINT #stream, expression [, expression...] 

where stream is the stream specified for this file when it was opened. 

For example: 

PRINT #addressf i le/SurnameSCi),address$(i),phone(i) 

expression is any string or numeric expression, which will be evaluated to produce 
text which will then be output to the file, in a format almost exactly as would be 
printed to a text screen using PRINT. The only important difference is that Tab 
Control codes (ASCII 9) are not expanded to spaces. This format can be controlled 
with USING, ZONE. TAB, semicolons and commas, as described previously for 
PRINT. 

Each time a PRINT # stream instruction is executed for this stream, the 'printed' 
information is 'written' onto the end of the file, until the file is closed. 

(In fact, information is not written immediately, but stored in a small area of memory 
called a 'buffer'. The contents of this buffer are only written to the disc when the 
buffer becomes full, or the file is closed. Buffering is used to make the system more 
efficient, by reducing the number of times the disc drive has to be turned on and 
off.) 

The purpose of creating a file with PRINT #stream is to put information in it that 
can be read back into similiar variables later, using INPUT # stream. The simplest 
way to ensure this is to include just one item in each PRINT # stream instruction, 
with no trailing comma or semicolon (but see below). 

As remarked above, PRINT # stream is also used to output text to a particular text 
screen (or printer). By simply altering the OPEN command from OPEN OUTPUT to 
OPEN SCREEN, you can arrange for 'disc' output to be displayed rather than written 
to disc! This is particularly useful when debugging programs. 




Reading a file 

A sequential file is read in three stages: 

- opening the file for input 

- reading information from the file 

- closing the file 

Opening and closing files has already been described. 

Once the file has been opened for INPUT, information can be read from it using the 
commands INPUT # stream and LINE INPUT # stream , as follows. 

INPUT ^stream f variable [, variable...] 

For example: 

INPUT #file, surname$(i),address$(i),count(i) 

Information is read from the file in strictly sequential order (hence 'sequential file’): 
the first variable in the first INPUT #stream instruction will be assigned to from the 
first value in the file, the second variable from the second value, and so on. It is not 
possible to read backwards or re-read an item; to do this, you must open the file for 
input again, then read up to the required item again. 

The information read from a sequential file will not necessarily correspond with that 
written to it, unless due care has been taken with the provision of separators. INPUT 
#stream reads information from the file exactly as previously described for input 
from the keyboard, as follows: 

• When inputting to a numeric variable, spaces and tab characters ('white space’) are 
skipped over until a digit is read, characters are then read and assigned up to the 
next non-digit. 

• When inputting to a string variable, spaces and tab characters are skipped over until 
a non-white-space character is read. If this first character is a double quote (") the 
string is treated as a 'quoted string': all characters (other than null: ASCII 0) will be 
read and assigned up to the next double quote. Otherwise, characters will be read 
up to the next comma or carriage-return character (ASCII 13). 

Input to either type of variable is terminated if reading reaches the end of the file. 

LINE INPUT #stream is used as previously described for reading text from the 
keyboard: 

LINE INPUT #sfrea/r?, string-variable 

This reads characters up to the next carriage-return (ASCII 13) into the specified 
string variable, skipping over initial spaces, tab characters and line feeds. 

INPUT #stream can also be used to input text from the keyboard, by using a 
stream that is attached to a screen. Thus, by simply changing the OPEN INPUT 
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command to OPEN SCREEN, you can 'type' disc input rather than read it from a 
sequential file. Again, this is useful for developing and testing programs. (INPUT 
#stream is actually used with a screen stream to display the prompt and typed 
reply in a screen other than the default.) 

Using PRINT # and INPUT # 

The type and order of variables you should use in an INPUT #stream instruction are 
largely dictated by the structure of the file, which was in turn determined by the 
PRINT #stream instructions used to create the file. 

You will usually want to read information back from a sequential file exactly as it 
was written. The simplest way to ensure this is to use a separate PRINT #stream 
instruction for each item when creating the file. This will place a carriage-return 
character after each item written in the file, which is a valid separator for strings 
and for numbers. You can then read the file using INPUT # stream , with the same 
variable types in the same order as were used to create the file. For example, if the 
file was created using: 

file = 6 

OPEN #file OUTPUT "names" 

FOR i = 1 TO 10 

PRINT #file / surname$(i) 

PRINT #file / address$(i) 

PRINT #file,telephone(i) 

NEXT 

Then the information could be read back using: 

f = 10 

OPEN #f INPUT "names" 

FOR entry = 1 TO 10 

INPUT #f ,c lient$(i),address$(i),phone(i) 

NEXT 

Note that, as shown here, you need not use the same names for the variables, just 
the same types. 

This approach will work as long as you do not write to the file any strings with 
commas in them. If there are, you will need to write these as 'quoted strings' le 
surround strings with double quote characters (CHR$ (34)), as follows: 

PRINT #file,CHR$(34);address$(i);CHR$<34) 

Since PRINT #stream writes numerics to the file as text, you are quite at liberty to 
read numbers back as strings. Similarly, since separators are not inserted 
automatically between string items, you can easily read back as a single string, an 
item created by writing several separate items. You may well eventually find this 
flexibility very useful, but initially, you will probably be a lot safer to ignore these 
possibilities and follow the guidelines given here! 



Read position 

Attempting to read beyond the last data item in a file will generate an error. This 
can be avoided by knowing how many items are in the file, or even by adopting a 
convention of writing a unique value as the last entry in a file, then testing each 
item read against this. For example, if the end marker were "ZZZ", you could print 
the whole file using: 

REPEAT 

INPUT #file, itemS 
IF itemS <> "ZZZ” THEN PRINT itemS 
UNTIL itemS = "ZZZ" 

However, a more elegant method is to use the function EOF: 
result = E0F(#sfrea/7?) 

This returns a 0 ('false') while there are more items to be read from the file, -1 
('true') when the last item has been read. For example, to print all the entries in a 
file: 

WHILE NOT(EOF(#file)) 

INPUT #file, itemS 
PRINT itemS 
WEND 

Changing a sequential file 

BASIC 2 does not provide facilities to change particular items in a sequential file 
directly, but you can add items to the end of an existing sequential file by opening it 
with OPEN APPEND, then using PRINT # stream. 

If you need to change a sequential file in any other way. you must do so by creating 
a new version, consisting of information read from the old version and the changes 
required. 

If the file is small enough, you could read the entire file into an array, change the 
elements required and then write the revised version back to the disc, as illustrated 
in the phone book example below. 

If the file is too large to read in one go. you can still alter it. by reading information 
in batches and creating the new file by writing the revised version of each batch in 
turn. 

Designing programs using sequential files 

To illustrate programming using sequential files, two 'worked examples' will now be 
presented, in the following stages: 

- problem specification 

- design 

- example code 

- testing 

These examples will illustrate not only sequential file handling, but also use of other 
facilities (logic, structuring, functions, etc) described in previous chapters. 



Depending on your familiarity with BASIC, you may want to use this section as a 
further tutorial in design, or choose to attempt the problems yourself and ignore the 
guidance given here unless you get stuck! 

You may even find these programs useful, although that is not the prime aim of 
including them in this guide. If you'd rather not type them, you will find copies 
included on your disc. 

Feel free to try the effect of making minor changes to the programs, to help you 
understand how they work. 

(For more detailed guidance on designing and testing programs, see Parts D and IV 
and the chapter on programming tools, in this Part.) 


Example ----- 

Statistical analysis 

This example illustrates the simplest way to use information from a sequential file - 
by reading it an item at a time and using each item immediately. 

Problem 

The task is to total, count and average all the numerical data entries in a sequential 
file, then print this information together with the maximum and minimum values 
read, when the whole file has been read. The average should reflect the average 
magnitude ie ignore the signs of the numbers, but all other results should be based 
on the signs. 

The data in the file might be financial transactions, sizes of football crowds, 
temperatures; it doesn't matter what. The data items will all be numbers, positive or 
negative, integer or floating point, in the range -9999.999 to +9999.999. The Ble may 
have between zero and twenty thousand entries. The name of the data file will be 
supplied by the user when the program is run. 

IF YOU WANT TO TEST YOUR UNDERSTANDING OF THE FACILITIES DESCRIBED 
SO FAR, ATTEMPT TO DESIGN AND WRITE THE PROGRAM NOW WITHOUT 
READING ANY FURTHER. 

Design 

Since none of the processing requires access to previously read data, there is no 
need to store the data in an array. This is just as well, as an array with twenty 
thousand elements would probably not fit into memory! 

The program will consist of the following stages: 

- set up variables and screen 

- choose file 

- read and process entries 

- finish calculations and print results 

- tidy up 
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Program 

The Mowing is one way of coding the functions required by the design. 

REM simple statistical analysis program 
REM *** set up variables and screen *** 
file = 10 

SCREEN TEXT FLEXIBLE: WINDOW CURSOR ON 
nmaximum = -10000: nminimum = 10000 
count = 0: total = 0: total-absolute = 0 
CLS 

PRINT "Statistical analysis program" 

i 

REM *** choose file *** 

FILES 

REPEAT 

INPUT "Type name of file to analyse, followed by ENTER ";filename$ 
UNTIL FINDSCfilenameS) <> "" 

i 

REM *** read and process entries *** 

CLS 

PRINT "Analysing ";filenameS;" - PLEASE WAIT" 

PRINT 

OPEN #file INPUT filenames 
WHILE NOTCEOF(file)) 

INPUT #file,number 
GOSUB add_entry 
WEND 

i 

REM *** finish calculations and print results *** 

IF count = 0 THEN PRINT filenames;" is empty" ELSE GOSUB show-results 

i 

REM *** tidy up *** 

CLOSE #file 
END 

i 

REM *** SUBROUTINES *** 

i 

LABEL add_entry 
count = count + 1 
total = total + number 

total-absolute = total-absolute + ABS(number) 
nminimunt = MIN(number,nminimum) 
nmaximum = MAX(number,nmaximum) 

RETURN 

i 

LABEL show-results 
average = total-absolute/count 
PRINT "RESULTS FOR FILE ";filenameS 
PRINT 

PRINT "Final total:";TAB(40);total 

PRINT "Average absolute value of an entry:";TAB(40); average 
PRINT "Minimum value was:";TAB(40);nminimum 
PRINT "Maximum value was:";TAB(40);nmaximum 
RETURN 
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You should find that this program is largely self-explanatory. Note that the two 
subroutines ('add-entry' and ‘show-results') do not contain any file processing - 
they would be equally at home processing information typed by the user. 

While this program is a reasonable solution, it is by no means perfect. For example, 
the user cannot change discs or directones and the results could be displayed more 
neatly. Try enhancing the program along these lines. 

Testing 

The final stage in developing a program should be to test it. in as realistic a manner 
as possible As you haven't been supplied with any of the files that the program is 
designed to work with, you must generate them In keeping with the simple task, the 
following simple program can be used to generate a test file 

REM create test file for stats program 
OPEN #6 OUTPUT "testl.seq" 

FOR a = 1 TO 10 
PRINT #6,a 
PRINT #6,-a 
NEXT 

CLOSE #6 

Run this program to generate the test file, then analyse it using your analysis 
program. 

The ideal test produces results that you can easily check by independent means, 
while still pushing the program to its designed limits. A single test will rarely satisfy 
both aims. This simple test file produces results that you can easily check by doing a 
little arithmetic, but does not include the number or wide range of numeric values 
that the specification requires the program to be able to cope with. 

To save you the trouble of the arithmetic, the results should be: 


Final total: 0 

Average absolute value of an entry: 5.5 

Minimum value was: —10 

Maximum value was: 10 


Example -.---. 

Phone book 

This example will illustrate how to use a sequential file to set up an array (or 
processing in memory, giving the advantage of speed and access in any order. It also 
shows one way to 'update' a sequential file. 

Again, a copy of this program is included on your disc. 

Task 

The task is to provide a 'phone book', which the user can add phone numbers and 
names to and find phone numbers by typing just the name. To keep the program 
simple, other useful facilities such as editing entries and printing a sorted phone list 
will not be provided. 
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When specifying a name to search for, upper and lower case are to be considered 
equivalent and commas are not allowed. The whole name must be specified and 
only the first entry matching the name need be displayed. 

The maximum number of entries will be 100. The longest phone number (including 
STD code) will be 12 digits. The STD code can be stored as integral pan of the 
number The longest name will be 30 characters. 

The phone book file will have a fixed name. 

IF YOU WANT TO TEST YOUR UNDERSTANDING OF THE FACILITIES DESCRIBED 
SO FAR. ATTEMPT TO DESIGN AND WRITE THE PROGRAM NOW. WITHOUT 
READING ANY FURTHER. 

Design 

As the number of entnes is fairly small, the whole file can be read into an array in 
memory for ease and speed of processing. For the same reason, there is no need to 
sort the entnes into alphabetical or numerical order; the computer can find any 
particular name quickly by checking each element in turn. 

As the task descnption does not include a layout for the file, its design is up to the 
programmer The file must hold three types of information in the file: names and 
phone numbers (which are obvious) and the relationship between a name and a 
phone number This relationship could be stored by structuring the file in a number 
of ways 

• as a list of names, followed by a list of phone numbers (the nth name would then 
have the nth phone number) 

• as a list of entries consisting of each name followed by its phone number 

• as a list of entries consisting of a name plus a list of indexes to the phone numbers 
in a subsequent list (eg "AdAstra Inc",4,7 means that AdAstra Inc has phone 
numbers 4 and 7 in the phone number list) 

There is not much to choose between the first two methods, although the second 
would allow updating using OPEN APPEND, while the first would not. The third 
structure could cater for complex situations (such as one name having several phone 
numbers, or several names having the same phone number), but as these are not 
required by the task description and would be more difficult to program, it will not 
be considered further. 

The program will consist of the following stages: 

- set up variables and screen 

- read file and store entries 

- ask for and carry out instructions (search by name, add an entry, finish) 

- write file (if changed) and tidy up 
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Program 

The following is one way of coding the functions required by the design. Note in 
particular that the program does not change the phone book file as such; it changes 
the information held in memory and writes the file all over again! 

All file access occurs in the subroutines 'readfile' and ‘writefile'. 


REM phone book program 

I 

REM **** set up variables and screen **** 

SCREEN #1 TEXT: WINDOW CURSOR ON: WINDOW FULL 
limit = 100 

DIM namesS(limit),phoneS<limit) 
phone-fileS = "phone.seq": file = 6 
file-changed = FALSE 
CLS 

PRINT "Phone book" 

REM **** get data **** 

GOSUB readfile 

i 

REM **★* get and obey commands **** 

REPEAT 

CLS 

PRINT "Phone book 'gentries;" entries" 

PRINT:PRINT "Search for number. Add a number or Finish (S/A/F) 
templateS="SAF": GOSUB match 
commands = answers 

IF commandS="S" THEN GOSUB searchentry: GOSUB keywait ELSE IF commandS="A" 
THEN GOSUB addentry: GOSUB keywait 
UNTIL commands = "F" 

i 

REM **** finish **** 

IF file-changed THEN GOSUB writefile 
END 

i 

REM ***** * SUBROUTINES ****** 

i 

LABEL readfile 

entries = 0: got-file = FALSE: answerS="" 

REM ** check if file there ** 

REPEAT 

IF FINDS (phone-fi leS) <> "" THEN got-file = TRUE ELSE GOSUB file not found 
UNTIL (answers = "N") OR got-file " " 

IF NOT got-file THEN RETURN 
REM * file found so read entries * 

PRINT: PRINT "Reading phone book: please wait" 

OPEN #file INPUT phone-fileS 
WHILE NOT(EOF(#file)) 
entries = entries ♦ 1 
INPUT #file,namesS(entries) 

INPUT #file,phoneS(entries) 

WEND 

CLOSE #file 
RETURN 




LABEL file.not.found 
REM * no file * 

PRINT "No phone book file on this disc." 

PRINT "Change disc or start New phone book on this disc (C/N)? 
template$="CN": GOSUB match 
IF answers = "C" THEN GOSUB changedisc 
RETURN 

i 


LABEL searchentry 

IF entries = 0 THEN PRINT "Phone book empty!!!": RETURN 
INPUT "Type name to search for, then RETURN: ",search$ 
searchS = UPPERS(searchS) 
count = 1 

WHILE (count <= entries) AND (namesSCcount) <> searchS) 
count = count + 1 


WEND 

IF count > entries THEN PRINT searchS;" 
RETURN 


not found" ELSE 

PRINT "Phone number: ";phoneS(count) 


LABEL addentry 

IF entries >= limit THEN PRINT "No room!!!": RETURN 
INPUT "Type name to add followed by RETURN: ",idS 
INPUT "Type number to add followed by RETURN: ",phoneS 
entries = entries + 1 
namesS(entries) = UPPERS(idS) 
phoneS(entries) = phoneS 
file.changed = TRUE 
RETURN 

i 

LABEL writefile 

PRINT: PRINT "Writing phone book: please wait" 

OPEN #file OUTPUT phone.fileS 
FOR count = 1 TO entries 
PRINT #file,namesS(count) 

PRINT #file,phoneS(count) 

NEXT 

CLOSE #file 
RETURN 

i 


LABEL changedisc 
RESET 

INPUT "Insert phone book disc then press RETURN",aS 
RETURN 

i 

LABEL match 
REPEAT 
REPEAT 

answers = UPPERS(INKEYS) 

UNTIL answerSo"" 

UNTIL INSTR(templateS,answerS) > 0 
PRINT 
RETURN 
« 

LABEL keywait 

PRINT: PRINT "Press any key to continue" 

REPEAT 

UNTIL INKEYS <> "" 

RETURN 


SEQUENTIAL 

FILES 



Again, this program is by no means perfect. For example, you must always type the 
complete name when searching and there is no check for duplicate entries. You 
could also use OPEN APPEND to update the file. 

Try changing the program to correct these deficiencies. 

(HINT: To search using incomplete names, either use INSTR (which will search for 
any part of the name), or LEN to check the length of the typed name and then 
substrings to compare it with the same length of stored names.) 

(HINT: To allow entries to be changed by specifying an existing name, search 
through the array each time when adding an entry and replace an existing entry that 
matches, only adding new ones to the end of the array, but be careful to adjust the 
\entries' count accordingly.) 

Testing 

To test this program, run it to create a new phone book and add a few entries. Run 
it again, to check that it finds the existing phone book. Try all three options to see if 
they work. If you've got a lot of patience, check that it will handle the limit of 100 
entries correctly, or just change 'limit' to a smaller number and check that. 
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9. PROGRAM DESIGN 


This chapter serves as a sort of 'worked example' for the whole of Part HI. showing 
how to produce a fairly powerful program, using a wide range of BASIC 2 facilities. 

In doing so, it illustrates how to break a task down into stages (modules), recognise 
the keywords and structures that will be best suited to program each stage and 
build them up into the full program. 

To make the best use of the wide range of facilities provided by BASIC 2 you will 
need to adopt a deliberate and logical approach to program design. You should 
however find that your diligence is well-rewarded, in the form of useful and reliable 
programs, produced without tears! 

Steps in design 

As described in Part II, developing even the simplest program involves a number of 
fairly distinct activities. By carrying these out deliberately and in a logical order, you 
can reduce the amount of effort needed to produce programs and improve their 
quality. 

The steps that we would suggest are: 

• Analysis: deciding what the program has to achieve 

• Design: deciding how the program will achieve its tasks 

• Coding: preparing and typing the program 

• Testing: checking that the program works correctly 

• Documentation: writing instructions for users/programmers 

• Maintenance: correcting and improving the program, helping users 

While the amount of effort given to each step will vary enormously with the 
complexity of the program, the skills of its users, the importance of its function, etc. 
you should always at least consider each, at the appropriate phase of program 
development. 

Each of these steps will now be applied to the development of the example 
application, a picture-drawing package, called 'PICT. Depending on your fa miliari ty 
with BASIC and with program design, you may prefer to work through the following 
or simply read it. 

A version of PIQ is also included on your disc. 
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Analysis 


PIQ should allow you to draw pictures on the display using the mouse, save an 
entire picture to disc and load an entire picture from disc. 

To keep the program simple. PIQ need only allow you to draw: 

7 points 

- lines 

- boxes 

- circles 

And supply the following additional commands: 

- Save picture 

- Load picture 

- Clear picture 

- Delete last item drawn 

- Finish 

PIQ does not need any text facilities. It should be simple to use. write and 
understand! 

Design 

To make the program simple to use, the mouse will be used for input wherever 
possible, for example by using ‘menus' to select commands. 

To make the program simple to write, built-in GEM facilities will be used wherever 
possible, eg by leaving the user to select the line type, size and colour, using the 
Lines and Colours menus. (This does however mean that when pictures are loaded 
and saved, the line type, size and colour used will be forgotten; this will be tolerated 
as it is only a simple program!) 

The obvious stages required are: 

(PROGRAM) 

initialise variables and screen 
repeat 

execute command 
until command is exit 
finish 

The main stage that obviously needs further decomposition is 'execute command'. 

As described previously, the user picks commands from a menu, using the mouse 
so the first two steps are: 

display command menu 

read mouse until command selected 

The final step is to obey the command selected, so 'execute command' becomes 

(EXECUTE COMMAND) 
display command menu 
read mouse until command selected 
obey command 





So, the main stages are: 

(PROGRAM) 

initialise variables and screen 
repeat 

display command menu 
read mouse until command selected 
obey command 
until command is exit 
finish 


Coding 


A version of PIQ is supplied at the end of this chapter. If you examine it. you should 
be able to see the stages described previously quite clearly, as they have been 
coded as the following main subroutines: 

- initialise 

- list-commands 

- pick-command 

- obey-command 

- final 

The other subroutines used in the program are: 


Name 

do-point 
do-line 
do-box 
do-circle 
do-delete 
do-clear 
do-save 
do-load 

redraw 

store-command 
scan-point 
prompt 


Action 

plot a point 
draw a line 
draw a box 
draw a circle 
delete last item 
delete all items 
save picture 
load picture 

draw picture from 
stored commands 
add command to 
stored commands 
input a position 

print prompt in 
menu window 


Used by 


obey-command 
obey-command 
obey-command 
obey-command l 
obey-command 
obey-command 
obey-command 
obey-command ^ 


commands 


do-delete and do-load 


do-point, do-line, do-box and 
do-circle 

pick-command. do_point. do_line, 
do _ box and do _ circle 
list-commands, do.point, do-line, 
do-box, do-circle, do-save and 
store-command 


Rather than describe each subroutine in detail, brief notes will be given to explain 
certain key aspects of their design and coding. 

Initialise (variables) 

The variables and data structures needed by a program are dictated by the 
information that it must store and the ways it must process that information. 

*01 


PROGRAM DESIGN 





The most complex information that must be stored is the commands (and 
parameters) used to draw the picture. These must be stored to allow the program to 
provide the facility 'save picture' (and 'delete last command'). 

The user draws a picture by entering a sequence of commands and parameters. The 
most obvious way to store such a list is by using an array. The parameters are all 
numeric (integers, specifying positions), while the commands can be represented by 
any distinct tokens, such as numbers. 

Commands and their parameters could be stored using a single multi-dimensional 
array, separate single-dimensional arrays (for the command and each parameter), or 
a single-dimensional array of records. The latter method, offering the advantage of 
using less memory, was chosen. 

Initialise (screen) 

The main task of this program is to draw pictures on the screen, so the most 
obvious requirement is for a graphics window, which I will call the 'Picture 
window'. 

Do you need any other windows? Commands are picked from a menu which must 
be displayed, as must prompts to tell the user to enter information such as positions 
for items in the picture. Both require text. While this could be displayed in the 
Picture window, a rather neater solution would be to use a separate window for the 
menu and prompts. (This will also make operation rather quicker, as less of the 
screen will need to be updated when prompts are changed.) 

To keep the display simple and leave more room for the picture, a single extra 
window can be used, shared between the menu and prompts. I will call it the 
'Menu window’. To simplify command picking, this will be a graphics window. 

How should the screens and windows be defined? The picture screen should be as 
big as possible, to allow the user maximum flexibility, so its dimensions should be 
set using the functions XDEVICE and YDEVICE (these return the display's 
resolution, which is the maximum size allowed for a graphics screen). 

The Menu window need only display a single line of text at a time and there is no 
need for scrolling, so its screen can be defined as fixed to the same size. 

The Picture window should be as large as possible, to allow the user to see as much 
of the picture at a time as possible. 





Should the windows be separate or overlapping? To simplify the program and 
reduce the time taken to redraw windows, they should be kept separate, so the 
display will look something like: 



Display command menu 

The Command menu is text, consisting of command names or acceptable 
abbreviations. It performs two functions - reminding the user of the commands 
available, and serving as a ‘target’ that the user points at to select commands. 

To simplify picking commands from the menu, each menu cell (command) should be 
the same length and the menu bar should be a single line. As there are only nina 
options, each of which can be identified by a word of 6 or less characters, the menu 
will fit easily across the full width of the screen. 

The menu is printed as a single string variable, in the menu window, after naming 
it of any prompts. Since this is very similar to printing a prompt, the code to do this 
can be shared. 

Read mouse until command selected 

Programs can read two types of information from the mouse: the position it is 
pointing to on the screen and whether its buttons are being pressed. A combination 
of pointing and button-pressing ('clicking') is used to pick options from GEM menus 
and so will also be used to select commands from the program's Command menu 
To lessen confusion with GEM’s windows, we'll use the tight button for selection! 
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The mouse position is read using the functions XMOUSE and YMOUSE. which 
return the position in screen co-ordinates. This can be converted to a menu cell 
number by taking into account the menu window's size and position, and the width 
of each menu cell. 

The function BUTTON (2) returns -1 unless the rightmost mouse button is being 
pressed. 

Thus, to read the mouse until a command is selected, the program should loop until 
BUTTON (2) is not -1 and the mouse is within the menu area, as indicated by 
XMOUSE and YMOUSE. 

This part of the program is coded as a subroutine; it sets a single numeric value (the 
command number). 

Obey command 

The neatest way to implement 'obey command' is to keep independent the code 
required for each command. Thus, separate subroutines are needed to: 

- Draw a point 

- Draw a line 

- Draw a box 

- Draw a circle 

- Delete the last item drawn 

- Clear the picture 

- Save the picture 

- Load the picture 

To complete most of these commands, the program needs additional information 
from the user, such as position and radius (to draw a circle), or file name (to save a 
picture). The information required depends on the command, so the obvious solution 
is to include the prompting and input handling in the subroutine dealing with the 
command. 

So, for example, ‘Draw a circle' becomes: 

(DRAW A CIRCLE) 
get circle centre 
get circle radius 

draw a circle with that centre and radius 

However, while the details of the input required depend on the command, there are 
two obvious common factors in most of this input: displaying a prompt and reading 
the mouse. To economise on code, the following two subroutines are shared: 

display a prompt: 'prompt' 
input a point: ‘scanpoint' 

Note that 'scanpoint' has to set two numeric values: the point’s x and y 
co-ordinates which are then assigned to other variables after the subroutine has 
returned. 

Prompts are simply displayed in the menu window, after clearing it. 

(To economise on code, both subroutines are also shared with command picking 
from the menu.) 



A final stage is needed with those commands that change the picture, to store the 
command and its parameters, so that when the picture is saved (or redrawn) later it 
will be complete. This is done by assigning the command code and parameters to a 
record, incrementing the 'stored records’ pointer and assigning the record to the 
next element in the array of stored records (ie storeS(stored)). 

The program 


REM PIQ - drawing progran 
GOSUB initialise 
REPEAT 

GOSUB list.commands 
GOSUB pick.command 
GOSUB obey.command 
UNTIL command = 9 
GOSUB final 
END 

REM PROCEDURES and FUNCTIONS •** 

LABEL initialise 

REM * constants and declarations • 
file = 5 

picture * 2: REM picture stream 
menu = 1: REM menu and prompts stream 
stored.limit = 100 

DIM storedSCI TO stored.limit) FIXED 17 
RECORD cir; code BYTE, xl WORD, yl WORD, radius WORD 
RECORD other; code BYTE, xl WORD, yl WORD, x2 WORD, y2 WORD 
REM * set up menu * 

menus = "point..line., .box... .circle.delete. clear, .save. ..load.. .quit..." 
REM code:1 23456789 
recJ=STRINGS(17, " "> 

REM * set up streams, screens and windows • 

REM picture stream 
WINDOW ^picture CLOSE 

SCREEN #picture GRAPHICS: REM screen as big as possible 
cell.width ■ 7*XCELL(#picture)/XPIXEL(#picture) 
menu.width = LEN(menuS)*XCELL(#picture)/XPIXEL(#picture) 
menu-height * YCELL(#picture)/YPIXEL(#picture) 

WINDOW Rpicture SIZE XUSABLE, YUSABLE-S*YCELL/YPIXEL 

WINDOW #picture SCROLL 0;0 

WINDOW #picture PLACE 0; 3*YCELL/YPIXEL 

WINDOW Ipicture CURSOR OFF 

WINDOW ^picture TITLE "•* PICTURE **" 

WINDOW Rpicture OPEN 
REM menu stream 
WINDOW emenu CLOSE 

SCREEN #menu GRAPHICS menu.width FIXED, menu.height FIXED 
WINDOW #menu PLACE 0; menu.height-YWINOOW 
WINDOW #menu CURSOR OFF 
WINDOW #menu TITLE "menu t prompts" 

WINDOW #menu OPEN 

• • • i 

REM * aero counters * 
stored = 0 
RETURN 

mi 

LABEL final 
CLS fpicture 
RETURN 

LABEL list.commands: REM display menu of commands 
messageS*menuS 
GOSUB ask.prompt 
RETURN 

• « « • 

LABEL pick.command: REM return command number when button pressed and 
mousein menu 
where B menu 
GOSUB scanpoint 

command ■ 1 ♦ x\(cell.width*XPIXEL(#menu)) 

RETURN 

Mil 

LABEL obey.command 
where*picture 

ON command GOSUB do.point,do.line,do.box,do.circle,do^elete,do.clear,do. 

save,do-load,do.nothing 

RETURN 
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LABEL do-nothing 
RETURN 

mm 

LABEL do-point 

arssagcSOtove souse to point end click": COSUB ask-proapt 
COSUB scenpoint 
reel.other.code = 1 
recS.other.xl ■ x 
recS.other.yl * y 
PLOT epictore, x;y 
GOSUB store.coaaand 
RETURN 

• 9 • t 

LABEL do-line 

aessageS="Nove souse to line stort and click": GOSUB ask-prospt 

GOSUB scenpoint: x1*x: y1=y 

reef.other.code * 2 

recS.other.xl * xl 

recS.other.yl * yl 

sessegeS» >a Hove souse to line end end click": GOSUB ask-prospt 

GOSUB scan-second: x2*x: y2=y 

reel.other.*2 * x2 

recS.other.y2 ■ y2 

LIRE apicture, x1;y1, x2;y2 

GOSUB store.cownd 



LABEL do-box 

sessegeSOtove to bottos left BOX comer end click": GOSIA ask-prospt 

GOSUB scenpoint: x1»x: y1*y 

red.other.code ■ 3 

red.other.xl * xl 

red.other.yl • yl 

sessagcS^Otove to opposite corner of BOX end click”: GOSLB esk-prospt 
GOSUB seen.second: x2*x: y2*y 
x2«x2-x1: y2*y2-y1 
red. other.x2 > x2 
red. other. y2 ■ y2 
BOX apicture, x1;y1, m 2 , y2 
GOSUB store-coasend 
RETURN 

LABEL do-circle 

sessageSOtove to circle centre end click”: GOSIB ask-prospt 

COSUB scanpoint: x1»x: y1»y 

red.cir.code ■ 4 

red.cir.xl ■ xl 

red.cir.yl ■ yl 

sessageSOIove to any point on cireference end click": GOSIB esk-prospt 
GOSUB scan-second: x2»x: y2*y 
x ■ <x1-x2 12 
y ■ Cy1-y212 
radius - FLOOR(S«(x*y» 
red.cir.radius ■ radius 
CIRCLE apicture, x1;y1, radius 
GOSUB store-coasend 
RETURN 

MM 

label do-delete 

IF stored > 0 THEN stored ■ stored - It GOSUB redrew 

RETURN 

IMI 

LABEL do-clear 
stored ■ B 
CLS #pictore 
RETURN 

mm 

LABEL do-save 
CLS #aanu 

IF stored - B THEN ■essegeS>”NOTHING TO SAVE! !*’: GOSUB esk-prospt: RETURN 
INPUT «aenu,”Nase to save file under";filenead 
OPEN #file OUTPUT filenaaof 
FOR a ■ 1 TO stored 
PRINT #file,storedS(e).other.code 
PRINT #file,storedS(a).other.xl 
PRINT afile,storedMa).other.y1 
PRINT Bfile,atoredS(a).other.x2 
PRINT (pfile^storedKe).other.y2 
NEXT 

CLOSE Bfile 

RETURN 

MM 

LABEL do-load 
REPEAT 
CLS Paero 

INPUT anenu, "Naas of file to lood";filenaaet 
UNTIL FlNBSlfi lenassS)o"" 

OPEN #ffle INPUT filenawS 


stored = 0 

WHILE NOT(EOF(#file)> 
stored = stored ♦ 1 

INPUT at He,storedS(stored).other.code 
INPUT afile,storedS(stored).other.xl 
INPUT afile,storedS(stored).other.yl 
INPUT afile,storedS(stored).other.x2 
INPUT afile,storedS(stored).other.y2 

WEND 

CLOSE afile 
GOSUB redrew 
RETURN 

LABEL redraw 
CLS apicture 
FOR a - 1 TO stored 
reel = WHOLES(storedS(a)> 
code = reel.other.code 

ON code GOSUB cese.point, cese.line, case-box, case-circle 
NEXT 
RETURN 

LABEL case-point: PLOT apicture, recS.other.x1;recS.other.yl: RETURN 
LABEL case-line: LINE apicture, recS.other.x1;recS.other.yl, recS 
.other.x2;recS.other.y2: RETURN 

LABEL case.box: BOX apicture, recS.other.x1;recS.other.yl,recS 
•other.x2,recS.other.y2: RETURN 

LABEL case.circle: CIRCLE apicture, recS.cir.x1;recS.cir.y1, recS.cir 
.radius: RETURN 

LABEL store.coasand 

IF stored=stored-liait THEN aessageS="NO ROON!": GOSUB ask-pro^jt: RETIKn 
stored = stored ♦ 1 
storedS(stored) = WHOLES(recS) 

RETURN 


LABEL scan-second 

HOVE Awhere,x1;y1 : WINDOW awhere CURSOR ON : GOSUB scar*»int 
WINDOW awhere CURSOR OFF 
RETURN 


LABEL scanpoint 
REPEAT 

REPEAT: UNTIL (BUTTONd) > -1) OR <BUTT0N(2) > -1) 
x = XHOUSE-XPLACE(awhere) 
y = YHOUSE-YPLACE(awhere) 

UNTIL x» 0 AND x<= XWINDOW(awhere) AND y>- 0 AND y<* YWINDOW(awhcra) 
x=x*XPIXEL(awhere): y=y*YPIXEL(awhere) 

CLS Paenu 

REPEAT: UNTIL (BUTTONd) < 0) AND (BUTT0N(2) < 0) 

RETURN 


LABEL ask-proapt 
CLS amenu 

PRINT Aaenu, aessageS; 
GOSUB wait.5 
RETURN 


LABEL wait-5 
t-TIHE 

REPEAT: UNTIL TIHE>t*50 
RETURN 



PART IV: ADVANCED FACILITIES 


This part describes advanced facilities which, while not vital to 
understanding or using BASIC 2, will help you to produce really 
effective and reliable programs. 
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1. RANDOM FILES 


As described previously, you can use three types of data file: sequential, random 
and keyed files. The first was described in a previous chapter: this chapter describes 
how to use random files. 

Random files are quite similar to sequential files: they also have names, must be 
opened before they are used, can have information written to or read from them and 
should be closed after use. 

However, random files have two major advantages over sequential files: 

- the information in them can be read in any order (hence random rather than 
sequential access) 

- information can be changed directly (also in any order) 

These differences make random files easier to use than sequential files for many 
applications. Against these advantages, random files are a little more difficult to 
understand and use properly, and will usually take up more space on the disc for the 
same amount of information. 

This chapter describes the fundamental concepts of random file handling, how to 
create, read and write to random files and concludes with a number of worked 
examples illustrating these principles in action. 

Some versions of BASIC 2 will support multi-user systems. If you wish to make sure 
that programs you write will be suitable for use on such systems, refer to the 
chapter on 'multi-user systems' (or see locking). 


Records 


Information is stored in a random file using a rather different method to that used in 
a sequential file. In a sequential file, each data item is written and read 
independently, and the different items can have different lengths. In a random file, 
items are read and written as fixed-length strings called 'records’. All the records in 
a random file have the same fixed length. While records can consist of single data 
items, they usually consist of several data items packed together. 

Records provide a convenient way to store related pieces of information together. 
For example, in a personnel file, you could use a single record per employee, 
containing all the information about that person, for example: 

- Name 

- Address 

- Phone 

- NI number 

- Date of birth 

- Pay scale 

- Insurance scale 

Keeping all this related information together makes a lot of sense, ensuring that the 
right name is used with the right phone number, etc. 
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., record is identified for reading and writing by its position in the file - its 'record 
number'. The first record is number 1, the second number 2, and so on. BASIC 2 
will allow you to use over 8 million records per file, although a lower limit may be 
imposed by the size of files your disc drive can handle. 

A record is thus referred to rather like a variable in a (single dimensional) array, 
which is specified by its index (eg person$(2)). In fact, you might like to think of a 
random file as an array of record variables, which is no longer limited in size by the 
computer's memory and can be shared easily between programs! 

Record numbers 

Random files are often used to hold information on individual items, such as people, 
companies or products with one (or some other fixed number of) record being used 
per item. Programs can then be designed to allow users to select easily record(s) to 
view, change, print etc. 

The best way to design a file for this type of application is to position each record in 
the file according to some numeric information that users can easily associate with 
the item, such as an employee's code or an item's stock number. 

If this is not possible, you will usually have to invent a record number for each item, 
write it down and then tell users to specify the information required by this number, 
so that 'ACME Motor Insurance' becomes company 1. 'ACME National' company 
2. etc. (Keyed access, described in a subsequent chapter, provides a much more 
eiegant solution, however!) 

Commands and functions 

The commands used with random and keyed files can also be used almost like 
functions, returning a numeric result that can be assigned to a variable. This result 
indicates the success or failure (and reason for failure) of the operation. 

Thus 

command parameters 

can be used as: 

result = command parameters 

Note that the parameters should not be placed in brackets, and that this is not a 
true function, so cannot be used in any other way, such as in an expression. 

A result of 0 indicates complete success. A result of greater than 0 and less than 
100 indicates 'qualified success' - a minor failure which will not terminate execution 
or invoke normal error handling. A result greater than or equal to 100 indicates a 
minor ('non-fatal') error - the result is the error code. A serious ('fatal') error will 
cause the program to terminate or invoke error-handling, if this is active. 

If used as a command, any sort of error will terminate the program or invoke 
error-handling. Complete and qualified success will both allow the program to 
continue and the program will not be able to distinguish them. 

Using file-handling commands as functions makes it simpler to write good, reliable 
programs that can cope with errors such as incorrect file names. 


(In fact, any command can be used in this way, not just file-handling commands. 
This topic will be described in detail in the chapter on error-handling and will not be 
described further here.) 

Processing a random file 

A random file is processed in four main stages: 

open the file 
define record structures 
process a record - repeated as necessary 
close the file 

Each stage will now be described in turn. 

Opening a random file 

Before you can use a random file, you must 'open' it using the command OPEN: 

OPEN #stream [qualifier] RANDOM file-name /LENGTH length] 

stream is an integer expression in the range 0-15, which you will use in all 
subsequent instructions to refer to this file. Numbers in the range 0 - 2 are usually 
used to write to the printer and screen window streams, so you will usually use 
numbers 3 - 15 for disc access, stream must not already be open (to a disc file, 
screen, printer, graphics device, etc.). 

file-name is a string expression giving the complete name used for the file. 

length specifies the length (in characters) of records in the file. If omitted, a length 
of 128 characters is assumed. This allows you to use disc space more efficiently 
when you need less than 128 characters per record, or need more than 128 
characters per record. If opening an existing file, you will usually want to specify the 
same record length as was used to create it. 

qualifier may be NEW or OLD. If NEW, the file must not already exist, or an error will 
result. If OLD, the file must already exist, or an error will result. 

If qualifier is omitted, and if the file named already exists, it will be opened without 
affecting its contents. If the file named does not already exist, it will be created and 
opened. Its length will be zero. 

An existing file can be opened to read and/or change it. If you want to be sure to 
create an empty file, you can check if there is already a file with the same name and 
delete it if found (using FINDS and KILL). 

OPEN sets the current position (see below) to the first record in the file. 

You can open as many files as there are spare streams. If you reach this limit (which 
is unlikely!), you will have to close one of the streams that is already open (see 
CLOSE, below). 

A file stays open until you close it (as follows). You should not remove a disc 
containing an open file until it has been closed (if it is being written to. information 
may be lost). 
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Defining record structures 

Information is stored in random files as fixed-length strings called records. A record 
may consist of only a single item of information, but will usually consist of several 
items, packed together into the string. These packed items are called 'fields'. 

To simplify changing and using fields in a record (or any string, for that matter), you 
can declare their position and format using a RECORD statement. This defines a 
name, storage class and position for each field These field names can then be used 
to identify fields in a string, allowing you to use parts of the string almost like 
normal variables, while still leaving them packed into the string. 

RECORD has already been described in a previous chapter (see RECORD), but is 
used as follows. 

RECORD record-name ; field [,field...] 

record-name is a simple numeric variable name (ie any valid variable name without 
$ or array suffix). This name will be used for the record structure; it is entirely 
distinct from any variable with the same name. 

field defines a field, as: 

field-name[( range) ] [storage-class] 
or field namd$(( range)] FIXED length 

field-name is a simple variable, which is entirely separate from any variables or 
other field names in other records. It must be unique within this RECORD. 

(.range), if included, specifies that the field is a single-dimensional array, as 
described previously for DIM. 

storage-class is used to reduce the size of a numeric field, by limiting the range of 
values that can be stored in it. It may be any of BYTE, UBYTE. WORD, UWORD or 
INTEGER, as described previously for DIM. 

The space used by each field type is as follows: 

Field Characters 

field-name 8 

field-name$ FIXED n n 

BYTE. UBYTE 1 

WORD. UWORD 2 

INTEGER 4 

(Arrays use the same space per element.) 

For example: 

RECORD stock; idS FIXED 30, held INTEGER, bin$(1 TO 3) FIXED 5, cost 


id$ 


held bin$(l) bin$(2) bin$(3) cost 


31 


35 


40 


45 


50 


58 










Once a field has been defined using RECORD, it is used to qualify a string 
expression, as: 

string-expression, record-name. field-name[( subscript) ] 

This returns a result which is the value of the corresponding position in the 
string-expression, interpreted according to that field's defined storage class. 

Similarly, a field is assigned to using: 

string-variable, record-name, field-name [(.subscript) ] 

This form can also be used in INPUT statements, with READ, etc - almost 
anywhere that a variable of the same type could be. 

Before a field can be assigned to, the string must be initialised. It is recommended 
that STRING is used for initialisation. 

For example, assuming that fields have been defined using the previous RECORD 
statement: 

tempS.stock.id$ = "horse radish peroxidase" 

assigns the string "horse radish peroxidase" to characters 1 to 30 of tempi, padding 
with trailing nulls. 

PRINT "Stock held is";temp$.stock.held 

prints the numeric resulting from considering the characters stored at positions 
31 to 34 of tempi as a signed integer. 

Note that while record structures are always used with string expressions, the result 
produced may be string or numeric, depending on the field's type. 

You can define as many record structures as you want, so that you can easily create 
or read records with quite different layouts. BASIC 2 does not enforce any fixed 
relationships between the record structures or types of fields used to create and to 
read fields. 

For example, in the personnel file described above, there might also be records for 
unpaid juniors, which will be laid out differently because they must store different 
information. You would then need to define two different record structures to cater 
for the two record types: 

The employee structure: 

RECORD employee; type BYTE, idS FIXED 30, addressS FIXED 50, 

phoneS FIXED 10, ni.numbers FIXED 9, birth_date$ FIXED 6, 
pay.scaleS FIXED 1, ins.scaleS FIXED 1 

The junior structure: 

RECORD junior; type BYTE, id$ FIXED 30, addressS FIXED 50, phoneS 
FIXED 10, birth_dateS FIXED 6, experience$<1 TO 5) FIXED 10 

Then, after reading a record, a program can decide if it is an employee's record or 
junior's record (eg by the value of tempS.employee.type) and use the appropriate 
record structure. 
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Note that the two record structures are of different lengths When the file is created, 
its record length must be set to accommodate the longer type. 

Processing records 

Once a file has been opened and record structures defined, you are ready to add. 
read or change records. Note that with a random file, you can do these in any 
combination, any order - there is no need to finish writing a file before reading from 
it. 

Current position 

As described above, the record to read or write can be identified by its record 
number, which is its position in the file. (There are also other ways to specify the 
position, as described below) If no position is specified, the record is read or written 
at the 'current position'. 

The current position is set to the first record (1) when the file is opened and may 
thereafter be changed by positioning commands. 

To determine the current position, use the functions LOC or POSITIONS 

result - LOC (.#stream) 

result is an integer, the current position’s record number 
result = POSITION$(#sfream) 

result is a string, which specifies the current position in a form suitable for use with 
the 'AT' position specifier (see below) (This function is mainly used for positioning 
in keyed files, as described in the next chapter.) 

To move to a given position use the POSITION command: 

POSITION #stream position 

position specifies which record to move to. as follows: 

NEXT - the next record after the current position 
AT record-number - the specified record number 

AT position-string - the record specified by position-string, which must have been 
produced using the function POSITIONS (as described above) 

eg ptr = L0C(#f) 

ptrS = P0SITI0N$(#f) 
and AT ptr 
AT ptr$ 

Writing records 

Records are written to a random file using the command PUT: 

PUT #stream, string-expression (position] 

stream is an integer expression identifying the file to be written to. as described 
above for OPEN. 

string-expression is the string to write to the file. If this is longer than the file's 
record length this will produce an error; if shorter, it will be expanded by adding 
trailing nulls (ie addding zero bytes to the right). For most uses, this string will have 
been constructed using record fields, as described above. 



If position is not specified, the record is written to the current position. Note that 
the current position is not changed by this! 

If there was a record already at the written position, it is replaced without error. 

If there was no record at the written position, (ie the record was written beyond the 
end of the file) it will be written to the required position and the file length will be 
increased to include the new record. In the gap from the old end of the file to this 
new record, there will be a number of records that have not been written to. These 
records may have any contents whatsoever. 

By using PUT and POSITION NEXT, records are written in turn, rather like in a 
sequential file. This is the quickest way to write a random file, as the disc drive 
does not have to keep finding different parts of the file, position is specified in other 
ways mainly when changing or reading an existing file, or creating a file when it is 
too difficult to generate records in record number order. 

Reading records 

Records are read from a random file using the command GET: 

GET #stream, string-variable [position] 
stream and position are as described above. 

The record read is assigned to string-variable. For example: 

GET #f, rec$ AT ptr 

If the record read has never been written, the string returned by GET is entirely 
unpredictable, which is likely to cause problems! To avoid this possibility, either 
make sure than every record in the file has been written to before reading it 
(perhaps using a unique record marker for 'unused' records, such as all nulls), or 
write your programs so that they never read unwritten records. 

If the record read is beyond the end of the file, an error results. This can be avoided 
by controlling reading with EOF. EOF is a function, used as: 

result = EOF(#sfream) 

result is -1 (true) if the current position is beyond the last record in the file, 
otherwise 0 (false). 

For example, to process a random file sequentially, you can use a simple loop: 

OPEN #f iLe RANDOM file$ 

WHILE N0T(E0F<#file)> 

GET #file, rec$ 

(process rec$) 

POSITION #file, NEXT 
WEND 

CLOSE #file 

The records in a random file will usually be created using fields, as described above 
(see RECORD). If a program needs to use information from these records, it will 
need to use identical fields defined using a similiar RECORD command. The fields 
used must have exactly the same type and size and be in the same order as defined 
when creating the records, although the record structure and field names may 
totally be different. 
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Each type of field is written to the disc in a different internal format, which are quite 
incompatible. For example a value assigned to a BYTE field (for instance) and 
written to disc will be read quite differently using a string field! Thus, there is no 
automatic conversion of types, such as provided for keyboard input, screen output 
and input/output with sequential files (see INPUT # and PRINT #). 

Note that BASIC 2 does not check field types in records: it is up to you to ensure 
that they are compatible. 

Changing records 

To change a record, you must simply write to its position in the file. (If you need the 
information it contains currently, read it first!) 

Records can be added to the end of the file, by setting the current position to the 
last record +1 and then using PUT and POSITION NEXT. To find the end of a file, 
you could read to its end by using a POSITION NEXT loop controlled by EOF. but a 
much more efficient method is to use the function LOF: 

result - LOF (.^stream) 

result is an integer, giving the length of the file, in bytes. It follows that the last 
record's number is: 

CEI LING C LOF (.# stream) / record-length) 

NOTE: CEILING is used to cater for the case where the length of the file is not an 
integral number of records. 

Records cannot be inserted into the middle of a random file, nor deleted. If you need 
to insert a record, you will need to copy the file a record at a time to another 
version, inserting the extra record at the appropriate place in the copy. To delete 
records, you could copy the file, simply skipping over the records to be deleted (ie 
not copying them), or write a unique 'empty' record to the records to be deleted. 

Closing a random file 

When you have finished with the file, close it using the command CLOSE. This: 

- ensures that any information written to the file has actually been transferred to it 

- allows the file to be opened again 

- frees that stream for re-use 

Files are closed with the command CLOSE: 

CLOSE 

CLOSE #stream [,#stream...] 

The first form closes all disc files that are open 

The second form is used to close specific streams. For example: 

CLOSE #6, #client_f i le, #stockfile 

Open files are also closed automatically on exit from BASIC 2. 



Designing programs using random files 

To illustrate programming with random files, three simple example programs will 
now be presented, as "worked examples’. Versions of these may be supplied on 
your disc. 

Example program: Creating a simple random file 

As a simple introduction to working with random files, we shall now develop a 
program to store as records lines of text (people’s names) typed by the user. 

You may care to attempt the detailed design and coding yourself, or take a more 
relaxed attitude and just watch it all happen before your eyes. A version of the 
program may be included on your disc. 

As described above, processing a random file consists of four stages: 

1 Open the file 

2 Define record structures 

3 Process a record - repeated as necessary 

4 Close the file 

Each stage will now be considered in turn. 

Stage 1 

Stage 1 is opening the file. A random file is opened using OPEN, as follows: 

OPEN #stream RANDOM file-name /LENGTH record-length] 

stream can be any valid unused stream. For example, 5. To improve legibility and 
simplify changing the program, stream should be defined as a variable. 

file-name is a string expression, giving the file name. The file name chosen should 
suggest the role of the file, for example, examp Lei. ran or names. Again, to 
improve legibility and simplify changing the program, this should be a variable. 
Check the disc first if you want to be sure that there isn't already a file with this 
name. 

The record-length determines the maximum amount of information per record. In 
this program, the information being stored is a string, so record-length is the 
maximum number of characters per record. The items being stored are names, 
which are unlikely to exceed 30 characters each. To accommodate the odd 
exception, assume a maximum of 40 characters, so record-length should be 40. 

So, the code for Stage 1 becomes: 

fiLeno = 5 
filenames = "lines" 
reclength = 40 

OPEN #fileno RANDOM filenames LENGTH reclength 

Stage 2 

Stage 2 is defining record fields. As there is only one item of information being 
stored per record, this is strictly unnecessary, but a good habit to get into! The 
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name will be a maximum of 40 characters, and a string, so a suitable RECORD 
statement is: 

RECORD n; persons FIXED 40 

Stage 3 

Stage 3 is processing records. By referring to the initial description, the processing 
for a single record can be broken down to: 

3a Input name 
3b Write name to the file 

3a can be an INPUT instruction, from the keyboard, for example: 

INPUT "Type a name, followed by RETURN",idS.n.persons 
3b is a PUT instruction: 

PUT #stream, string-expression [position] 

stream is the same as used to open the file, ie fileno. 

string-expression is the variable containing the name le id$. 

So instruction 3b is: 

PUT #fileno, id$ 

3c Move to next Record 
POSITION #fileno, NEXT 

That concludes writing a single record. This must of course be repeated, or the file 
created will consist of just the one name! This requires a loop. Which type of loop? 
FOR, WHILE or REPEAT? To make the program flexible, it should allow the user to 
stop after any number of names, rather than have to decide how many at the start, 
so a FOR loop (which needs to 'know' how many repetitions are required before 
starting) is not suitable. A REPEAT loop is slightly better than a WHILE loop, 
because it needs one less instruction (to set up the test before entry), so: 

REPEAT 

INPUT "Type a name, followed by RETURN",id$.n.persons 
PUT fileno, idS sPOSITION #fileno, NEXT 
UNTIL 'finished' 

What does 'finished' mean? It must be a test that the user can affect easily, to stop 
looping. The user could be asked after each name whether another is required, but 
that would require two replies per name - a bit laborious. It is much neater to have 
only a single reply from the user per name, so instead, adopt a convention that an 
'unusual' name will stop the loop. For example, a null name, so the last line of the 
loop becomes: 

UNTIL idS ="" 

To tell the user how to quit the program, extend the INPUT prompt: 

INPUT "Type name then RETURN, or RETURN to quit",id$.n.persons 

Finally, to avoid writing a null name to the end of the file, change the PUT 
command to: 

IF idS <> "" THEN PUT #fi leno, idS rPOSITION #fileno, NEXT 


This concludes Stage 3. The code is now: 

REPEAT 

INPUT "Type name then RETURN, or RETURN to quit",id$.n.persons 
IF id$ <> "" THEN PUT #f ileno, id$ zPOSITION #fileno, NEXT 
UNTIL idS = "" 

Stage 4 

Stage 4 consists of closing the file. Files are closed using CLOSE: 

CLOSE 

or CLOSE # stream [,#stream...] 

The first form closes all open disc files, while the latter closes particular streams. 
Since this is the only file open. Stage 4 can consist of: 

CLOSE 

The program 

By joining together the four stages developed above (in order!), the following 
program is produced: 

fileno = 5 

filenames = "lines" 

rec length = 40 

RECORD n; persons FIXED 40 

OPEN #fileno RANDOM filenames LENGTH reclength 
REPEAT 

INPUT "Type name then RETURN, or RETURN to quit",id$.n.persons 
IF idS <> "" THEN PUT #fi leno, idS zPOSITION #fileno, NEXT 
UNTIL id$ = "" 

CLOSE 

Even as small a program as this could be improved considerably, but it has been 
kept simple deliberately. 

You may care to try out the program. To see the file produced, run the program 
developed in the next worked example. 

Example program: Reading a simple random file 

We shall now develop a program to read names from the file created by the previous 
example program. To show a little of what random files are for. this program will not 
read records sequentially (as the file was created), but read records in any order, as 
requested by the user. 

You may care to attempt the detailed design and coding yourself, or take a more 
relaxed attitude and just watch it all happen before your eyes. A version of the 
program may be supplied on your disc. 
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As described above, processing a random file consists of four stages: 

t Open the file 

2 Define record structures 

3 Process a record - repeated as necessary 

4 Close the file 

Stages 1, 2 and 4 are exactly as described for writing the file, so will not be 
described again. 

Stage 3 

Stage 3 consists of processing a record. This must achieve the program's task, of 
displaying the record (name) corresponding to the record number typed by the user. 
Thus, the program must: 

3a Ask which record 
3b Read that record 
3c Display it 

3a is a simple INPUT instruction, requesting a number. (While it would be nice to 
inform the user of the legal range of record numbers and check what is typed for 
legality, this is a little too ambitious at this stage. If you don't agree, you’re ready to 
try it on your own!). For example: 

INPUT "Type the number of the name, then RETURN",rec_number 

3b requires a GET instruction, taking the form: 

GET # stream , string-variable [position] 

string-variable is the variable to use for the record read, so a suitable name is recS. 
stream is the stream used to open the file ie fileno. 

What about position ? This is used to read a record from other than the current 
position. As the program is designed to read records by their record number, it is 
needed and should be AT record-number. 

3b is thus: 

GET #fileno, rec$ AT rec.number 

3c can be a simple PRINT instruction, using the record field n.persons to extract 
the string: 

PRINT recS.n.persons 

So, to process a single record, the instructions are: 

INPUT "Type the number of the name, then RETURN",rec_number 
GET #fileno, recS AT rec.number 
PRINT recS.n.persons 


This group of instructions should be repeated for each name requested by the user. 
Again, this requires a loop, but a rather more difficult one. A FOR loop is again not 
suitable, because it would require the user to specify how many records he wants to 
read, in advance. Either a WHILE loop or REPEAT loop might be used. For example, 
using REPEAT: 

REPEAT 

INPUT "Type the number of the name, then RETURN",rec_number 
GET #fileno, rec$ AT rec.number 
PRINT rec*.n.person* 

UNTIL -finished' 

■finished' is the test that the user must be able to influence easily, to stop looping. 
Again, it would be neatest to have an 'unusual' reply to the prompt as the signal to 
stop looping. This should be a number that is not used as a record number in the 
file, for obvious reasons! For example, a record number of 0 (since the lowest record 
number is 1), giving the test as: 

UNTIL rec_number = 0 

Unfortunately, this approach has a major flaw; 0 is used because it is an invalid 
record number, yet when you type it. the program will immediately try to read a 
record for that number, producing an error - the loop will only exit after this abortive 
attempt! 

The solution is to only read the record if the record number is legal, producing the 
following: 

REPEAT 

INPUT "Type name's number or 0 to quit, then RETURN",rec_number 
IF rec_number > 0 THEN GET #fileno, recS AT rec_number: 

PRINT rec$.n.person* 

UNTIL rec_number = 0 

This version of the loop works correctly and will be used in the final program. Note 
how the prompt also tells the user how to quit. 

The program 

The full program is as follows. 

fileno = 5 

filename* = "lines" 

reclength = 40 

RECORD n; person* FIXED 40 

OPEN #fileno RANDOM filename* LENGTH rec_length 
REPEAT 

INPUT "Type name's number name or 0 t6 quit, then RETURN",rec_ number 
IF rec.number > 0 THEN GET #fileno, rec* AT rec.number: 

PRINT rec*.n.person* 

UNTIL rec_number = 0 
CLOSE 
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If you have typed this program, you may want to try it out. You will need to have 
typed and run the previous worked example first, or there will be no file for it to 
read! 

If you have worked through the above, you might like to devise improvements to the 
program. For example, how could you stop the error which results when a record 
number is typed which is beyond the end of the file? (The crucial point is knowing 
how long the file is. Use the function LOF.) 

Example: A personnel system 

The real power of random files is that a program can read, write and change records 
in them with gay abandon. The following, more complex, example may give you a 
taste for this power! 

The task 

The task is to allow users to create, maintain and examine a simple personnel file, 
for up to 500 personnel. The information to be stored is: 

- Employee number (1 - 999) 

- Name (30 characters) 

- Address (50 characters) 

- Phone (10 characters) 

- NI number (9 characters) 

- Date of birth (6 characters) 

- Pay scale (1 - 20) 

- Insurance scale (1 character) 

The facilities required are: 

- add a record 

- delete a record 

- replace a record 

- display a record 

- print a record 

The record to process will be selected by typing the employee number. 

IF YOU WANT TO TEST YOUR UNDERSTANDING OF THE FACILITIES 
DESCRIBED SO FAR, ATTEMPT TO DESIGN AND WRITE THE PROGRAM NOW 
WITHOUT READING ANY FURTHER 

The design 

The maximum amount of information to be handled (approximately 500*100 = 
50,000 characters) precludes storing the data in a sequential file and processing it in 
memory, as does the need to be able to update the records easily. A random file is 
(surprise, surprise!) quite suitable. 

The file structure will be considered next. Since records will be requested by 
employee number, the obvious order to put records in is by that number. Since the 
employee number is 3 digits, employee numbers can range from 1 to 999, producing 
999 records in the file (which would be approximately 100,000 bytes long). The 
maximum number of employees is stated as 500, which would produce a file that is 
half empty. This doesn;t seem too wasteful, so there is no need for a more complex 
relationship: the record number used for an employee will be the same as the 
employee number. Note that this means that the employee number does not need to 
be stored in the record - it is given by the record number! 


The stages involved in processing a random file (as described above) are: 

1 Open the file 

2 Define record structures 

3 Process a record - repeated as necessary 

4 Close the file 

As this is meant to be a 'real' task, 1 and 4 will be extended slightly, to produce 
neater results. So. the overall design is: 

1 Initialise variables, display and file 

2 Define record structures 

3 Process a record - repeated as necessary 

4 Close the file and tidy up 

Note that the file created by this program is quite large - there may not be room for 
it on the disc containing BASIC 2. 

Stage 1 

Stage 1 is fairly straightforward, except that the program does not just work with an 
existing file, but must also be able to create an empty file if none is found. An 
empty file should consist of 999 'empty' records (ie records that have been written 
with some special marker), to simplify processing. 

Thus, Stage 1 is something like: 

set up variables 

define text screen and windows 
clear display 
print title 

if no file, create an empty file 
open file 

The second step is not strictly necessary, but by using separate windows for 
displaying records and prompts, a much neater result can be produced. 

Stage 2 

Stage 2 can be deduced easily from the task description. There need be only one 
type of record, so you need define only one record structure. For simplicity, this 
structure can consist of all string fields with lengths as defined there; there is little 
to be gained from storing the ‘numeric’ data (such as phone number) as numeric 
fields, since they will only be read and written, not manipulated. 
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Stage 3 

Stage 3 is the most complex. For a single record, it must: 

prompt user for an option 
obey option: 
add a record 
delete a record 
replace a record 
display a record 
print a record 

While this would work, it would be a bit laborious to program and awkward to use 
For example, after selecting an option, each of the instructions would need to 
prompt for a record number, read the record and display it just to make sure that it 
was the right one. It would be far better for the user to select a record, see it, then 
decide what (if anything) to do with it: 

prompt user for record number 
read record 
display record 
prompt user for option 
delete 

replace (add) 

print 

skip 

Is this all? Remember that the record read may be blank, or already written. 
Different options apply to each type. An existing record can be deleted, replaced 
(added) or printed, but a blank record can only be added (replaced) - the other 
options make no sense! It would thus be much better to offer different options 
depending on whether or not the record is blank. 

Of course, this group of instructions must be repeated ie placed in a loop, so Stage 3 
consists of: 

repeat 

prompt user for record number 
read record 

if empty, prompt user: add/skip 
add, if selected 
if written, display record 
and prompt user: delete/replace/print/skip 
delete, if selected 
replace, if selected 
print, if selected 
prompt user: finish/continue 
until option=finish 




■■ 

Stage 4 

Stage 4 is again quite simple, consisting of closing the file and tidying up the 
display. 

Detailed design 

By combining Stages 1 to 4 of the above design, the following is produced: 

(Stage 1) 
set up variables 

define text screen and windows 
clear display 
print title 

if no file, create an empty file 
open file 

(Stage 2) 

define record fields used 

(Stage 3) 
repeat 

prompt user for record number 
read record 

if empty, prompt user: add/skip 
add, if selected 
if written, display record 
and prompt user: delete/replace/print/skip 
delete, if selected 
replace, if selected 
print, if selected 
prompt user: finish/continue 
until option=finish 

(Stage 4) 
close file 
clear window 
END 
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2. KEYED FILES 




Sequential files are most useful for storing information that will only be ever needed 
in one particular order. Random files are useful for storing information that may be 
wanted in any order, but only allow you to choose the particular piece of information 
(record) wanted in one way, by its record number. 

A more sophisticated and versatile form of random access is provided by ‘keyed 
files’, which are similar to the 'ISAM' (Indexed Sequential Access Method) files used 
on large commercial computers (mainframes and minicomputers). Although quite 
common on mainframe and minicomputers, this very powerful type of access is 
rather rare on microcomputers. 

Keyed files can be read and written in any order, just like ‘ordinary' random files. 
Their major advantage is that instead of having to specify a record by its record 
number, you can use any of a number of ‘keys' defined for that record. Keys are text 
or numeric labels that records are tagged with in the file. 

Using keyed files, the personnel file program described previously could easily be 
rewritten to allow the user to select records by employee name. National Insurance 
code, or even some other characteristic stored as a key (such as sex or department). 

If you think of a file as a printed book, to find a topic in a random file you must 
already know the page number; to find a topic in a keyed file, you can just look it 
up in the index! 

Keyed files are quite similar to random files, described in a previous chapter. To 
minimise duplication, this chapter will concentrate on the differences. 

For simplicity, this chapter will describe using keyed files as three quite separate 
processes; 

• Creating a new keyed file 

• Reading a keyed file 

• Changing (writing to) a keyed file 

The chapter concludes with worked examples, illustrating many of the points 
described. 

Note: versions of BASIC 2 will support multi-user systems. If you wish to write 
programs so that they can be used on these systems without changes, you should 
also refer to the chapter on ‘multi-user systems' (or see 'locking'). 
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Keys, indexes and index files 

Each keyed file can have up to twenty different sets of keys, each set being called 
an 'index'. Indexes are numbered 1 to 20. 


KEYED FILES 







All the keys in a single index must be of the same type. This must be one of the 
following: 

- integer: BYTE. UBYTE, WORD, UWORD or INTEGER 

- fixed length string, up to 30 characters 

- a variable length string, up to 30 characters 

In effect, each index provides a separate method of reading the keyed file 

When created, keys are placed in (numeric or alphabetic) order within an index, 
with duplicate keys being added in chronological order. 

Each index is usually used to hold a different type of key, such as names in Index 1, 
salary scales in Index 2, departments in Index 3, etc. You can choose whether or not 
to allow duplication of keys within an index (see KEYSPEC). Each record has at least 
one key in one of the indexes. You can have multiple keys for a record, in the same 
or different indexes. 

A program using a keyed file chooses which index to add keys and to read keys 
from, depending on the type of search (type of key) required. For example, to print 
records in alphabetical order of employee name, a program would read through an 
index that contained names; to find employees in a particular department, it would 
read through the index with department numbers in it. 

A keyed file actually consists of two files: a 'data file’, containing the data records 
and an "index file", containing the keys used to access it. 

Note that the order of records within a keyed data file is completely irrelevant; as 
records are always read via their keys, it is the order of the keys wit hin the 
index you are using which is. in effect, the record order. 

In many ways, you can consider a keyed file with ' n ’ indexes as if it were ’n’ 
separate files, that use shared records! 

The advantages of keyed files over separate files are numerous. For example: 

- any changes to the data are immediately effective regardless of which index ('file’) 
you use 

- a keyed file is more compact 

- information can be 'moved' or 'copied' between indexes ('files’) very easily 

To summarise, then, keyed files provide all the benefits of 'ordinary' random files, 
but are much better suited to information that will need to be accessed by a variety 
of 'hooks' rather than just by the record number. 

Commands and functions 

As described for random files, the commands described in this chapter can be used 
as functions, returning a result which indicates the success or failure of the 
operation. 

This facility will be mainly of interest if producing 'bulletproof programs and is 
accordingly described in the chapter on error-handling. It will not be described any 
further here. 


Creating a keyed file 

A keyed file is created in five separate stages: 

- opening the file 

- defining record fields 

- processing (writing) a record - repeated as necessary 

- closing the file 

Opening the file 

A keyed file is opened using the OPEN command: 

OPEN # stream [qualifier] RANDOM file-name INDEX index-name 
/LENGTH record-length] 

stream is an integer expression in the range 0 - 15, which you will use in all 
subsequent instructions to refer to this file. Numbers in the range 0-2 are usually 
used to write to the printer and display, so you will usually use numbers 3-15 for 
disc access, stream must not already be open (to a disc file, screen, printer, 
graphics device, etc.) 

file-name is a string expression giving the complete name used for the data file. 

index-name specifies the name for the index file, similarly. 

record-length specifies the length (in characters) of records in the file. Record length 
is recorded in the red tape at the start of a keyed file. If the keyed file is created by 
the OPEN command then the record length is set to that given, or 128 if none given. 
If the keyed file already exists then the record length must match the one given - if 
none is given then no check is made. 

qualifier may be NEW or OLD. If NEW, neither file must already exist, or an error will 
result. If OLD, both files must already exist, or an error will result. 

If qualifier is omitted, if both files already exist, they will be opened without 
affecting their contents. If neither file already exists, they will be created and 
opened. (If only one of the files exists, an error results.) 

If you want to be sure to create an empty keyed file, you can check if there are 
already files with the specified names and delete them if found. Note that you must 
do this for both the data file and the index file: 

IF FIND$(filenameS) <> "" THEN KILL filenames 
IF FINDSfindexnameS) <> "" THEN KILL indexnameS 

You can open as many files as there are spare streams. If you ever reach this limit, 
you will have to close one of the streams that is already open (see CLOSE, below). 

A file stays open until you close it (as follows). You should not remove a disc 
containing an open file until it has been closed (if it is being written to. information 
may be lost). 

If successful, this command creates two files: the data file and the index file. 
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Setting up indexes 

When you create a new keyed file, you must define each index before you can use 
it, using KEYSPEC: 

KEYSPEC #stream INDEX index [key-type] /UNIQUE switch] 

index specifies the index number being defined, key-type specifies the storage class 
of keys in that index. It may be any of: 

BYTE 

UBYTE 

WORD 

UWORD 

INTEGER 

FIXED length 

These storage types are as described previously for DIM. length is limited to a 
maximum of 30. If key-type is omitted, the keys will be variable length strings, of up 
to 30 characters. 

switch is a logical expression. If OFF (zero), duplicate keys will be allowed within 
the index. If omitted or ON (non-zero), keys within an index will be unique. 

Each index must be defined with KEYSPEC before it can be used. They can be 
defined in any order and unused indexes need not be specified. Each index must 
only be specified once. 

Correctly defined indexes make processing a keyed file much easier and quicker. 
Ideally, for ease of access, a keyed file should have an index for each type of access 
required (by name, by employee number, by department, by pay scale, etc). 
However, each index will need to be set up and will consume disc space, which 
may be at a premium. 

The storage and time required to search indexes increases with the key length, 
which is as follows: 


Key type Length 

BYTE and UBYTE 1 

WORD and UWORD 2 

INTEGER 4 

FIXED n n 


Note that there is no index type really suitable for numeric keys with fractional 
parts. 

A string index will still be required for many applications. For example, if a file will 
be searched by name, it makes more sense to use an index holding names than 
some number that the user or program must remember! 

But should they be variable length or fixed length? Use variable length strings unless 
the majority of keys will be the same maximum length. 

If using fixed length keys, how long should they be? Just long enough for the 
longest key you will want to use. This doesn't mean that the index length must be 
as long as the longest possible name (this might well prove impossible, given the 
limitation of 30 characters maximum), just that it should be long enough to allow 
keys that avoid (or at least minimise) duplication. 



Note that records are always positioned by a single key at a time - there is no 
facility to combine keys, for example to read records in age order within a 
department, or pick all unpaid bills for clients in a particular area. To produce a 
similar effect, you can create composite keys, by packing sub-keys into a single 
string key. using RECORD fields. Where the sub-keys are numeric, be sure to use 
the KEY qualifier in the record definition, eg. 

RECORD R; a BYTE KEY, b INTEGER KEY 

Defining record fields 

Record fields are defined, if wanted, using RECORD, exactly as described for 
random access files. For example: 

RECORD r; namelS FIXED 10, address* FIXED 50 

Writing records 

A record is first written to a keyed file using ADDREC, not PUT. This writes the 
record to the data file, and a single key for it to the index file: 

ADDREC #stream, string KEY key /INDEX index] 

stream is the stream used to open the file. 

string is a string expression, which will be written to the file. It will usually have 
been set up using RECORD fields, as described for random files. 

key is an expression giving the key to add for this record, which should be 
compatible with the index type. 

index specifies which index to add the key to. If omitted, the current index (ie index 
last used) will be used. 

Note that there is no facility nor need for positioning records in the data file. The 
position of records in the data file is irrelevant, while keys are automatically inserted 
in the appropriate (numeric or alphabetic) order within their index. 

Choosing keys 

The key chosen for a record must of course be one allowed by the KEYSPEC for that 
index. It is usual, but by no means obligatory, to add all keys to the same index 
when creating a file from scratch. You can always add more keys later (using 
ADDKEY - see below), or even more indexes (see KEYSPEC. below). 

If there is already a record with the same key in the index used, the key for the new 
record will normally be rejected, unless the index has been specified as allowing 
duplicates (as described previously, using KEYSPEC). when it will be accepted and 
placed after the existing key. 

To simplify generating unique numeric keys. BASIC 2 provides the function 
UNIQUE: 

result = UNIQUE (tstream) 

The result returned is an integer, which is 0 the first time UNIQUE is used for this 
file, 1 the next time, and so on. (The maximum result that will be produced is 
2,147,483,647.) 








(The numbers generated using UNIQUE can be used to link records between files, 
by using them as keys in a keyed file index and writing the same numbers as a 
pointer from the linked file's record.) 

Closing the file 

A keyed file MUST always be closed explicitly after writing or creating it. using a 
CLOSE instruction. 

It must NOT be left to be closed by leaving BASIC 2, or it will be unusable. 

This is because, while a keyed file is being changed, keys are buffered in memory, 
but data records are written to the disc. This means that the index file gets out of 
step with the data file. They are only guaranteed 'up to date' when the file is closed 
explicitly. BASIC 2 marks a file that is being changed as inconsistent, marking it 
consistent again only when closed. It will refuse to open a keyed file that is marked 
inconsistent. 

A keyed file can be made consistent by the command CONSOLIDATE: 

CONSOLIDATE #stream 

This writes all data to index and data files and marks them as consistent, without 
closing the keyed file. 


Reading a keyed file 

A keyed file is read in four main stages: 

- opening the file 

- defining record fields 

- processing (reading) a record - repeated as necessary 

- closing the file 

Records in a keyed file are selected for reading by their keys in the particular index 
being read, so that in many ways, it is more convenient to think of the process as 
reading keys from an index, with their associated records. 

Opening the file 

To open the keyed file, use: 

OPEN #stream [qualifier] RANDOM file-name INDEX index-name 
/LENGTH record-length] 

This has already been described, for creating a keyed file. 

Note that there is no need to specify length or define index types, as BASIC 2 
determines this information from data stored in the index file. 

Defining record fields 

If the record has a complex layout, you may wish to define fields using the RECORD 
command, as described previously. These should of course be consistent with the 
RECORD structures used when writing the records, if you want to be able to nco 
the information read! use 
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The current position 

The current position is a position in the index file (index and key) and corresponding 
position in the data file (record). It is unset when the file is opened and must 
therefore be set to a valid record before using the data. 

It is important because the current position is used by default in various reading and 
writing commands, if the position required is not specified. It is also used as a 
starting point when specifying the position required using NEXT. 

To set the current position directly, use the POSITION command: 

POSITION # stream position 

where position indicates the position required, as follows: 

NEXT 

- the next record after the current position in the current index 
AT position-string 

- the record specified by position-string - see POSITIONS 
KEY key /INDEX index] 

- the first record with the specified key, in the current or specified index 
INDEX index 

- the first key in index. 

To read the current position, use the function POSITIONS: 
position-string = POSITION $(#sfream) 

position-string can then be used to return to this position later, using GET AT, 
PUT AT, or the command POSITION: 

POSITION # stream AT position-string 

To check if the current position is at the end of an index (so that a NEXT would 
generate an error), use the function EOF: 

result = EOF (#stream) 

result is -1 (true) if the current position is at the end of an index, otherwise 0 
(false). 

The current key 

To determine the current key ie the key corresponding to the current position, use 
KEYS or KEY. according to whether the index type is numeric or string: 

numeric = KEY (^stream) 
string = KEY $(#sfream) 

These functions can be used, for example, to detect if the key has changed, when 
processing sequentially an index in which duplicates are allowed. For example, to 
print all records that have the key 'paid' in Index 3: 

POSITION #file KEY "paid" INDEX 3 
WHILE KEY$(#file)="paid" 

GET #file, recS 
PRINT recS 
POSITION #file NEXT 
WEND 









Note that this loop works because, if the current position is at the end of the index, 
KEYS returns a value bigger than any legal string key. With numeric keys KEY 
returns +2,147,483,648 which is bigger than any legal numeric key. 

Reading a record 

Records are read from a keyed file by using the command GET. 

GET # stream, string-variable [position] 

stream is an integer expression, specifying the stream number used to open the file. 

string-variable is the variable which will be assigned the record read. 

If position is not specified, the record is read from the current position. 

If specified, position indicates the record to be read. 

If the record is found, its key becomes the current position. 

If the required record cannot be found, an error will result. If you are not sure 
whether there is a record for the specified position, you should use the GET 
command as a function and check the result (0 indicates success). 

For example: 

result = GET #f ile, rec$ KEY namelS 

IF result = 0 THEN process(recS) ELSE PRINT namelS;" not found" 

Example! reading an index sequentially 

Suppose that you have a keyed file containing product information, with the 
following indexes: 

Index Contents 

1 product names (string, FIXED 10) 

2 part number (UWORD) 

3 supplier (FIXED 20) 

From it, you want to print a stock list and a price list. The pnce list should be in 

alphabetical order of product name, the stock list in numerical order of part number. 

To print the stock list, set the current position to the first key in the part number 
index, then read and print records until the end of the index, indicated by EOF: 

(open file, etc) 

partno.index = 2 

POSITION #file INDEX partno.index: REM start of part number index 
WHILE NOT EOF(#file) 

GET #file, rec$ : REM read record for next part number 
(print item as part number (eg KEY(#file)) and details from rec$) 

POSITION #file NEXT 
WEND 



Similarly for the price list: 

(open file, etc) 

names.index = 1 

POSITION #file INDEX names.index: REM get to start of name index 
WHILE NOT EOF<#file) 

GET #file, rec$ : REM read from next key in name index 

(print item as product name (eg KEY$(#file)) and cost, from rec$) POSITION 
#f i le NEXT 
WEND 

Note that the only difference in reading the file is in the index used in the POSITION 
command - '2' for part number order, '1' for product name order. 

Note also that the body of the loop is in the same form as would be used to read 
sequentially down a random file! 

Closing the file 

As stated above for creating a file, a keyed file must always be closed explicitly 
using a CLOSE instruction. 

It should not be left to be closed by leaving BASIC, or it may be unusable. 

This is because, when a keyed file is changed, index information will often get out 
of step with data records; only when an explicit close is executed (or 
CONSOLIDATE is used) will the keyed file be brought up-to-date and marked 
consistent. 

Changing a keyed file 

Changing a keyed file involves four separate steps: 

- opening the file 

- defining record fields 

- making changes - repeated as necessary \ 

- closing the file 

Opening the file, defining record fields and closing the file are exactly as described 
previously, for reading a keyed file. 

You may make any of the following changes to a keyed file: 

- add a new record 

- delete a record i 

- change an existing record 

- add a new index 

- add a new key 

- delete a key 

- change a key 

These changes can be made in any combination, but for simplicity, the following 
describes how to make each type of change separately, in turn. 

As described previously, a keyed file is marked as inconsistent as soon as it is 
changed and only marked consistent again when the keyed file is closed correctly. If 
the keyed file is not closed correctly, (eg because of a power failure), it will be left in 
an inconsistent state and marked as such. 
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Since you will not be able to use (open) a keyed file which is marked inconsistent, 
you should do two things to protect your keyed files from such a fate: always make 
a copy of the index and data files before beginning to change them and use the 
CONSOLIDATE command after each change or group of changes, as follows: 

The CONSOLIDATE command makes the keyed file consistent and marks it as such. 
It is used as: 

CONSOLIDATE #stream 

Adding a new record 

To add a new record, use the ADDREC function as described in 'Creating a keyed 
file', above. This adds a data record and a single key. If you want to add more keys 
for the record, use ADDKEY as described below. 

Deleting a record 

To delete a keyed record, you must delete each of its keys, using DELKEY as 
described below. When the last key for this record is deleted, the data record will be 
deleted too. 

(This will work correctly even if the keys for this record are duplicated.) 

Changing an existing record 

To change a record, you must either delete it (using DELKEY - see below) then add 
the new version (using ADDREC), or PUT the new version to its position in the file. 
All these steps are described elsewhere, apart from this particular use of PUT. 

PUT is used to rewrite the record rather than ADDREC, because ADDREC would 
add it as a new record: 

PUT #stream, string [position] 

position is the position of the record to change, defaulting to the current position, if 
omitted. This means that, for example, when rewriting a record, after reading it with 
GET and amending the record, you can simply use PUT without a position, to write 
it back to the same place. 

Adding a new index 

Indexes are defined for a keyed file using KEYSPEC, as previously described under 
'Creating a keyed file’. At least one must be defined before records can be added to 
the file, but further indexes can be added at any subsequent time, up to the limit of 
20 . 

Refer to the previous description of KEYSPEC for details. 

Note that KEYSPEC is used to add indexes - it cannot be used to replace them ie 
the index number specified must not have been used already. 

Adding a new key 

When you add a record to a keyed file using ADDREC, you specify a single key that 
must be used to access it. To add a key for an existing record, you must make it the 
current position (eg by using POSITION), then add the key using ADDKEY: 

ADDKEY #stream KEY key /INDEX index] 
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key is an expression yielding the key, which must be of a type suited to the index. 

index is an integer expression giving the index to add the key to. If omitted, the 
current index will be assumed. 

ADDKEY does not affect the current position. 

Extra keys can be added to any defined index, without limit, except for any 
restrictions on duplicate keys (see KEYSPEC). 

Deleting a key 

To delete the key for an existing record, make that record the current record and 
then use DELKEY: 

DELKEY #stream /KEY key /INDEX index]] 

This deletes the key specified for the current record, or the current key. Note that 
position can only be used to specify a key for the current record. 

DELKEY #stream AT position will delete a specific key. 

If the key is the only one for that record, the record will also be deleted. 

DELKEY does not change the current position, unless the key deleted is at the 
current position, in which case the current position moves to the next key. 

Changing a key 

To change a key, you must add the new key then delete the old one, in that order, 
using ADDKEY and DELKEY, as described above. The order is important to make 
sure that the record is not deleted with the key! 

Worked examples (keyed Hies) 

As a simple example of the use of a keyed file, two example programs will now be 
developed. The first will create a keyed file containing names and addresses for use 
by the second The second program will list the records in the first, in birthday order 
(ie 1st Jan to 31st December), or by sex. 

Creating a ‘birthdays Hie’ 

The main stages in creating a keyed file are as follows: 

1 Creating an empty file 

2 Defining record fields 

3 Writing records - repeated as necessary 

4 Closing the file 

The details of the design mainly rest on what information is to be stored (giving the 
record layout(s) required) and how it is to be searched (giving the number and types 
of indexes required). 









The information to be stored for each entry is: 

a Name 
b Address 
c Birthday 
d Sex 

The keys that will be used to search the file are: 

a Birthday 
b Sex 

Key types are defined using KEYSPEC: 

KEYSPEC # stream INDEX index [key-type] /UNIQUE switch] 

The keys required are: 

- sex: F or M 

- birthday: ranging from 1/1 to 31/12 
Thus, two indexes are needed, say 1 and 2. 

The 'sex' key type is quite simple. It can either be a single character string, or a 
BYTE, as it only has to store two alternatives. The former will be chosen, for 
simplicity (key types of M and F are more obvious than 0 and 1!) 

The type of key needed for 'birthday' is a little more complex to decide. 

This key is intended to make it easy to produce a sort of calendar of birthdays, so 
this index must be specified in a form that will be automatically sorted into calendar 
order. The form given (1/1. 2/1. 3/1 etc) is totally unsuitable: for example, the first of 
February (1/2) would come before the second of January (2/1) but after the first of 
December (1/12) etc. One solution is to use a form with a fixed width for the 
'months' and 'days' parts, with the 'months' part coming first, for example ' mmdd ': 
0101 for 1st January. 0102 for 2nd January ... 1231 for 31st December. This approach 
will be used. 

The range of keys needed for birthdays (0101 to 1231) could either be stored as fixed 
length strings (4 bytes each) or WORD/UWORD keys (2 bytes each). The latter will 
be used, for speed and economy of disc space. 

UNIQUE switch is used to allow duplicate keys in that index. Since duplicate sexes 
are certain (unless there are only two entries) and duplicate birthdays are certainly 
possible, it should be specified as zero or OFF (duplicates allowed) for both indexes. 
Thus, the indexes can be set up as: 

'sex' index: 

KEYSPEC #///e INDEX 1 FIXED 1 UNIQUE OFF 
'birthday' index: 

KEYSPEC #///e INDEX 2 UWORD UNIQUE OFF 

The data records consist of: 

- sex: 1 character 

- birthday: 1/1 to 31/12 

- name: say 30 characters 

- address: say 3 lines of 40 characters each 




The birthday could be stored as a number in the range 0101 to 1231 (as described 
for the keys) or as a text string (1/1 to 31/12). The former will be chosen for 
convenience. 

Record fields are defined using RECORD. The data record layout described 
translates directly into a record structure of (split over two lines for clarity): 

RECORD rec; sex$ FIXED 1, birthday UWORD, id$ FIXED 30, 
address$(1 TO 3) FIXED 40 

This requires a record of 153 (1+2+30+3 *40) bytes. 

Using these record structures and index types and the descriptions of keyed file 
processing provided earlier in this chapter, the following program should be quite 
easy to understand (if not. refer to the descriptions of the keywords used, in this 
chapter). 

REM * * * create birthday list * * * 

REM * constants and variables * 
ifileS = "birth.idx" 
dfile$ = "birth.dat" 
fi le = 5 
sex_index = 1 
birthday-index = 2 

REM * display * 

SCREEN TEXT FLEXIBLE 
WINDOW CURSOR ON 
CLS 

PRINT "Birthday list file creation program" 

PRINT 

I 

REM * set up file * 

CLOSE #5 

rc=KILL "birth.*" 'throw awy any old file 
OPEN #file NEW RANDOM dfileS INDEX ifileS LENGTH 153 
KEYSPEC #file INDEX sex.index FIXED 1 UNIQUE OFF 
KEYSPEC #file INDEX birthday-index UWORD UNIQUE OFF 

I 

REM * define record structures * 

RECORD rec; sex$ FIXED 1, birthday UWORD, id$ FIXED 30, 

address$(1 TO 3) FIXED 40 

r$=STRING$(153,0) 'initialise record string 

I 

REM * process records * 

REPEAT 

PRINT "Type name followed by RETURN " 

INPUT "or just RETURN to quit: ",r$.rec.id$ 

IF r$.rec.id$= "" THEN GOTO skipwork 
INPUT "Address line 1: ",r$.rec.address$(1) 

INPUT "Address line 2: ",r$.rec.address$(2) 

INPUT "Address line 3: ",r$.rec.addresS$(3> 

INPUT "Sex (F or M): ",sex$ 

INPUT "Month of birth (1-12): ",month 
INPUT "Day of birth (1-31): ",day 





r$.rec.sex$ = UPPER$(sex$) 
birthday = month*100 + day 
rS.rec.birthday = birthday 
ADDREC #file, r$ KEY sex$ INDEX sex-index 
ADDKEY #file KEY birthday INDEX birthday-index 
LABEL skipwork 
UNTIL rS.rec.idS = "" 

I 

REM * tidy up * 

CLOSE #f i le 
END 

(In the interests of simplicity, this program does not carry out any of the checks that 
a serious program would - for example, checking that the day and month typed by 
the user are within the specified range and legal (eg 30/2 is not, because there are. 
at most, 29 days in February). You may care to consider what checks are required 
and modify the program to incorporate them.) 

This program can be used to change records (using PUT), although this is more 
complex as you must be able to select which record to change if several have the 
same key. 

Reading the ‘birthdays’ file 

Reading the birthday list file to print lists in birthday or sex order should be quite 
straightforward, given the indexes that have been defined. Reading consists of four 
main stages, as described before: 

1 Opening the file 

2 Defining record fields 

3 Reading a record - repeated as necessary 

4 Closing the file 

Stage 1 uses OPEN to open the keyed file created by the previous program: 

OPEN # stream [qualifier] RANDOM file-name INDEX index-name 

stream can be any valid unused stream, but file-name and index-name must be the 
same as used to create the file. Note that record-length is not specified, as it will be 
determined automatically (from the index file). 

Stages 2 and 4 are exactly equivalent to the same stages used to create the file and 
will not be considered further. 

Stage 3 must ask the user whether records are required in birthday order or sex 
order, then read sequentially using the appropriate index and display each record in 
turn. Recovery of fields from the records is simple, using a record structure similiar 
to that used to create the record. Recovery of keys is a little more complex, 
consisting of a reversal of the process used originally to convert the sex or birthday 
into the key. 



; t 


Without further ado, the following program carries out these functions: 

REM * * * use birthday list * * * 

I 

REM * constants and variables * 
indfileS = "birth.idx" 
datfileS = "birth.dat" 
file = 10 
sex—index = 1 
birthday_index = 2 

REM * display * 

SCREEN TEXT FLEXIBLE 
WINDOW CURSOR ON 
CLS 

PRINT "Birthday file lister program" 

PRINT 

I 

REM * set up file * 

CLOSE #file 

OPEN #file OLD RANDOM datfileS INDEX indfileS 

I 

REM * define record structures * 

RECORD rec; sexS FIXED 1, birthday UWORD, idS FIXED 30, 
address$(1 TO 3) FIXED 40 

I 

REM * process records * 

REPEAT 

PRINT "List names in sex order (1)" 

INPUT "or birthday order <2)";ind 
UNTIL (ind=1) OR <ind=2) 

POSITION #file INDEX ind 
WHILE NOT EOF(#file) 

CLS 

GET #file, infoS 
PRINT infoS.rec.id$ 

IF infoS.rec.sexS = "F" THEN PRINT "Female" ELSE PRINT "Male" 

PRINT "Birthday: ";info$.rec.birthday MOD 100; 

PRINT "/";info$.rec.birthday \ 100 
FOR row = 1 TO 3 
PRINT infoS.rec.addressS(row) 

NEXT 

PRINT STRING$(40,"*") 

PRINT: PRINT "*** Press any key for next record" 

REPEAT 

UNTIL INKEYS <> "" 

POSITION #file NEXT 
WEND 

I 

REM * tidy up * 

CLOSE #fi le 
END 

Again, checking is kept to a minimum to keep the program simple. 

This program could quite easily be adapted to search for and report birthdays within 
the next 10 days. say. by using the computer’s calendar functions (using DATE and 
DATES). You may care to attempt this now. 
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Summary of data files 

The choice of data file type is usually dictated by the complexity of the information 
to be stored and the ways in which is must be accessible. 

Sequential files are the easiest to understand and begin to use, but limit the scope 
of programs considerably. Keyed files are the most complex and so most difficult to 
understand how to use, but will often make it much easier to carry out complex 
tasks. 

In general, sequential files are used for storing amounts of data which can be read 
through repeatedly to find the information required or read into memory and 
mani pulated there. They are also used for storing intrinsically sequential information 
(such as text) where there is no need for non-sequential access. A major limitation is 
that sequential files cannot be changed directly, apart from appending. 

Random files allow you to collect information into logical groups (records) then find 
particular records by their position in the file. Records can easily be added, changed 
or deleted. Random files are useful for things like indexes, stock control and storing 
many other types of business information. 

Keyed files have all the advantages of simple random files, with the additional 
advantage of being able to find records by using 'labels' (keys). Keyed files are by far 
the most versatile form, being ideally suited to storing information for different 
programs which can then access it in quite different ways. A well-designed keyed 
file can provide the heart of a sophisticated and versatile suite of programs, to 
handle complex tasks such as company payroll or accounts. 
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3. ERRORS AND ERROR HANDLING 


Types of error 


An error is anything that causes the program to produce incorrect results. 
There are five main types: 


1 Literal errors 

2 Coding errors 

3 Design errors 

4 Operator errors 

5 Hardware errors 


misspelt keywords, brackets missing from an expression, etc 

mistranslation of design into code eg using INPUT instead 
of INPUT #, or using an argument in degrees when the 
program is operating in radians 

faulty analysis of task into functions eg using a VAT rate of 
10%, or thinking that compound interest is calculated as 
principal* rate *period 

usually in input eg silly answers to prompts, pressing lar—*1 
by mistake, inserting the wrong disc 

attempting to use a corrupt or unformatted disc, power 
supply fluctuations, faulty computer chips 


Detecting errors 

Each of the five types of error is likely to show itself in a different way. 

Literal errors (Type 1) will usually stop the program, produce a message describing 
the type of error ('error message') in the Dialogue window and put you into the Edit 
window, with the cursor positioned near the cause. Certain types of error, such as 
faulty declaration of variables, procedures and functions, will be detected and 
reported very quickly when the program is run, but most other errors will only be 
detected and reported when the instruction containing the error is executed. 


Coding (Type 2) and design (Type 3) errors, while they may be indicated like literal 
errors, are usually more sneaky, producing incorrect operation of the program which 
will only be apparent if you check the results produced eg by comparing the results 
of performing calculations by hand. 


Operator errors (Type 4) will usually be reported by an error message from BASIC 2 
or the operating system, but only after the operator has made the mistake! 


Hardware errors (Type 5) will usually be very obvious, either being repotted by the 
operating system (as an operating system error message), causing the computer to 
seize up, or even producing some other strange behaviour. Luckily, with the 
increasing sophistication and reliability of computers, such problems are becoming 
quite rare. 
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Testing for errors 

While you may consider errors as a minor nuisance, to be sorted out only if and 
when they arise, a better and more efficient alternative is to actively seek out errors 
by testing programs or suites of programs, before using them in earnest. 

To test a program, you just need to use it and check that the results it produces are 
correct. To test it properly, you must make sure that all parts of the program are 
used and that all crucial parameters are pushed to their designed limits. 

For example, if a program is designed to total 100 numbers of -999999 to +999999 
each, then you should run it and test it with 100 numbers of -999999 and 100 of 
+999999, checking the result. 

Complex programs are notoriously difficult to test properly. The best way to test 
them is to test fully each stage (module) in the program individually, then carry out 
a simpler test on the complete program, to check that the modules work together 
correctly. Similarly, to test a suite of programs, test each individually first, before 
testing the complete suite. 

Good testing should be able to detect errors of Types 1, 2 and 3. 

Type 4 errors can be largely avoided by designing the program so that it behaves as 
the user expects, helps the user to understand what they must do and copes with 
common operator errors. Clear written instructions will also help. 

Type 5 errors are largely in the hands of the gods (or computer manufacturers!); the 
only errors that can be avoided by testing are those that result from running a 
program on a different computer configuration. For example, if the program is 
developed using a hard disc, but will be used with a floppy disc, check that it will 
work with one! 

Testing facilities 

BASIC 2 provides a number of facilities to help you test programs. 

The simplest to use are Ctrl-C. ? (PRINT) and CONT, to stop the program at crucial 
points, check the current value of particular variables, then make it carry on (as long 
as the program has not been altered). While rather crude, this is quite useful for 
quick checks on function. Note that ? is used rather than PRINT, to display output 
in the Dialogue window rather than using Stream 1. to avoid interfering with the 
program's screens. 

Slightly more 'upmarket' is the use of STOP and CONT. STOP is a command that 
causes the program to stop, printing a message to that effect. Variables can be 
displayed (? or PRINT), or even changed. As long as the program has not been 
changed, it can be restarted using the command CONT. 

The code of the most recent error is returned by the function ERR: 

result = ERR 

result is an unsigned integer giving the code of the last error generated since the 
program was run. or 0 if no error has occurred. 

Errors can also be simulated by the command ERROR: 

ERROR error 

error is an integer expression, giving the error code of the error to be simulated. 
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The error message associated with an error number can be found by using the 
ERRORS function: 

ERRORS ( error-number ) 

produces the error message associated with error error-number 

An error code of 100 indicates an operating system error. To determine the error 
code of the most recent operating system error, use the function OSERR: 

result = OSERR 

result is an unsigned integer, giving the operating system error code. Refer to your 
operating system documentation for a description of operating system errors and 

error codes. 

What to do about errors 

Once you've found an error, you'll probably want to do something about it! First, 
you must diagnose the source of the error. 

Error types 1. 2 and 3 are actually errors in the program, which you should correct 
using the editing facilities. If the error is in the design, it is best to correct the 
design first, then recode that part of the program - don’t, amend the program 
without thinking about it first! 

Diagnosis of Type 1 errors (literals) should usually be easy: the enor message tells 
you what is wrong with the line, which is indicated in the Edit window. 

Diagnosis of Type 2 (coding) and 3 (design) errors requires you to realise that a 
result is wrong, then find and correct the source of the error. For example, to track 
down an erroneous calculated result in a well-designed (!) program, you should be 
able to quickly find the module that produces the error, then work backwards 
through it until you reach a stage where the (interim) result is correct, and 
immediately subsequent to that should be the error. This will be much easier if you 
always write programs as small independent modules and test these, because then 
the area you have to check through will be much more manageable. 

A Type 4 (operator) error is not strictly an error in the program, but can be largely 
avoided by the programmer, by helping the user to do the right thing by designing 
sensible programs with helpful prompts and/or documentation, by testing that the 
user has done the right thing (eg testing typed input for validity before using it), and 
as a last resort, by using the error handling facilities described below. 

A Type 5 (hardware) error cannot be avoided by the program, but can to a certain 
extent be coped with by using the error handling facilities described below. 

Restarting a program 

If a program stops because of an error, you will usually be able to restart it by using 
CONT, provided you have not changed the program in any way. You can. however, 
display or change variables, redefine screens etc, if necessary while it is stopped. 
The program will continue with the next instruction after the one where execution 
stopped. 
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Bulletproof programs (well, almost) 

Errors detected by BASIC 2 (ie Types 1, 4 and 5) will usually produce an error 
message and stop the program. However, you can circumvent this and attempt to 
handle errors within a program, by using return codes or error-trapping, as follows. 

Command return codes 

Any of the commands described in this guide can be used almost like functions, 
when they will return a result ('return code') which indicates the success or failure 
(and reason for failure) of the operation ie 

command parameters 

can be used as: 

numeric-variable = command parameters 

Note that the parameters should not be placed in brackets. 

A command cannot be used as a true function; it can only be assigned to a numeric 
variable as shown here, not used, say, in an expression. 

This variable can then be used to check on the command’s operation. 

For example: 

check = OPEN #f, OLD INPUT fileS 
ok = LET answer = VAL(replyS) 

Note the LET command in the last example, which is obligatory when the command 
is an assignment. This is necessary to avoid ambiguity, because 'answer = 
VAL(replyS)' is a valid relational expression! (with a value of -1 if answer is equal to 
VAL(replyS), otherwise 0). 

The return code is 0 if the command was entirely successful. A result in the range 1 
to 99 indicates a 'qualified success’. A result greater than 100 indicates a 'non-fatal' 
error (for example, file not found, with an OPEN OLD command) - the result is the 
error code. A 'fatal' error (such as syntax error) will not yield a result, but it will 
cause the program to terminate or invoke error-handling, if this is active. 

Note that if used as a command, 'non-fatal' and 'fatal' errors will both terminate 
execution or invoke error-handling, if active, while 'complete' and 'qualified' success 
will both allow execution to continue and be indistinguishable. 

Error trapping 

A program can choose to intercept all errors, by using the ON ERROR GOTO 
statement: 

ON ERROR GOTO location 

location is a line number or label, which is the start of the ‘error handling routine’. 

After an ON ERROR GOTO statement has been executed, if an error occurs, instead 
of stopping the program and displaying an error message, execution will continue 
from the location. 

You can use multiple ON ERROR GOTO statements - the most recently executed 
one controls error handling. 


To turn off error handling use ON ERROR GOTO 0. 

The error handling routine can discover the type of error using the function ERR. as 
described previously and take appropriate action. 

If an error is generated within an error-handling routine, it is handled as normal ie 

by generating an error message and stopping execution. ! 

An error handling routine must exit with one of the following: 

RESUME 

This returns execution to the start of the statement that produced the error. 

RESUME location 

This returns execution to the specified location. 

RESUME NEXT 

This returns execution to the start of the statement after that which produced the 
error. 

Don't use error-handling as an alternative to the more conventional methods of 
avoiding errors, but as a last resort, for errors that you either have not anticipated, 
or that you cannot avoid using the methods described above. This will make your 
programs easier to understand, test and re-design. Error handling should mainly be 
used as a last-ditch attempt to stave off loss of data, in crucial applications such as 
updating large keyed files, where premature program termination could be' very 
inconvenient. 

Example , .. . . ... 

Vetting input type and range 

To input a number, the simplest instruction to use is INPUT with a numeric variable. 

For example: I 

INPUT "Number";month 

Better would be a prompt that actually tells the user what to do! For example; 

INPUT "Type the month <1 to 12), then press RETURN",month 

On its own, this does not guarantee that ’month' will have a value in the specified 
range (1 to 12). Include the instruction in a loop which tests the reply for validity and 
repeats the prompt until the reply is acceptable: 

REPEAT I 

INPUT "Type the month (1 to 12), then press RETURN",month 
month = FLOOR(month) 

UNTIL (month >= 1) AND (month <= 12) 

Note that the loop both forces the reply to integer and checks its range. 

Finally INPUT will object to a non-numeric, requesting the user to retype it 
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To protect the (rather careless) user bom this. INPUT to a string variable, then derive 
'month' bom that, using VAL. VAL will normally generate an error if the string does 
not convert to a number, so use VAL in an assignment command and check the 
return code: 

REPEAT 

INPUT "Type the month (1 to 12), then press RETURN",months 
ok = LET month = VAL(monthS) 

UNTIL ok AND (month >= 1) AND (month <= 12) 
month = FLOOR(month) 

Once this loop has been tested, you can use it and guarantee that the value of 
'month' will be in the required range on exit. 

A similar approach can be taken with other types of typed input (eg smgle character 
strings, options bom a list, etc). 

Example --- 

Don’t trust the outside world 

Simple programs tend to make a lot of assumptions - that the user knows how to 
use the program, that there is sufficient memory, that the windows are set up 
sensibly, etc. 

Bulletproof programs make just one assumption - that everything needed in the 
outside world will be in the worst possible state! The program must check on 
everything it uses and secure what it needs by taking appropriate action where it 
can, or by requesting help if it cant 

A typical example is a program that needs to read a disc file. A simple program 
might just OPEN it and accept that if the file isn’t there, the program will fail. 

A bulletproof program would check if the file is there, first, using FIND$: 

REPEAT 

INPUT "Type name of file to read, followed by RETURN";filenameS 
UNTIL FINDSCfilenameS) <> "" 

In this instance, the prompt is repeated until the named file is found. Depending on 
the program, a better solution might be to assume a certain independence and 
search other disc drives for the file if not found on the current disc. Alternatively, the 
user might be offered help, in the form of the directory for the current disc, or need 
to be allowed to change discs. 

(It would be even better to offer a ' menu' of suitable files on the disc, from which the 
user simply picks a file. This would ensure that the file was on the disc, of a suitable 
type and has its name spelled correctly!) 




Example 


Error handling 

As described previously, error handling is best kept in reserve for errors that cannot 
be handled well in any other way, or a catchall routine for handling anything you've 

forgotten! 

ON ERROR GOTO handler 


LABEL handler 

IF ERR = stopcode THEN INPUT "Do you want to quit (y/n)";a$: 

IF a$="y" OR a$= "Y" THEN STOP ELSE RESUME 


etc 


Another class of errors usually handled by ON ERROR GOTO are disc errors. 
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4. FINE-TUNING 


The rest of this guide has concentrated on the 'standard' behaviour of BASIC 2 ie 
how it behaves when first selected. 

There are however a number of options, controlled by software switches, which can 
be used to alter details of its behaviour; to fine-tune performance of programs to suit 
your particular needs or wants. 

Most of these switches can be changed at any time, using the command OPTION, 
followed by the switch name/setting, in the dialogue window or within a program. 

Each option has an initial setting (described below) which is set when entering 
BASIC 2. 


Angles 

BASIC 2 normally works with angles expressed in radians, but to switch to using 
degrees, use; 

OPTION DEGREES 

To switch back to radians, use: 

OPTION RADIANS 

A similar option is provided by the Program menu. 

Note that this affects the angles used throughout programs, with the exception of 
text written at an angle, which is always specified using degrees. 

Text output format 

Decimal fractions are normally output with a full stop as the decimal point character. 
To use a different character, use: 

OPTION DECIMAL point, separator 

point is a string expression, the first character of which will be used as a decimal 
point in all text output, to screen, printer, or sequential files, separator is a string 
expression, the first character or which will be used as the thousands separator 
when numbers are output with a USING template. Note that this has no effect on 
number input. 

Text output using a USING template can include currency symbols. This depends on 
the country code of your computer's operating system, but can be changed using: 

OPTION CURRENCYS character-string 

character-string is a string expression, the first n characters of which will be used 
as the currency symbol instead of dollar ($) signs, when using PRINT USING and 
the function DECS. (Where n is one less than the number of $ symbols in a $$$ 
USING template, or the number of $ symbols in a **$$$ template.) 





Date format 


The DATES function is used to convert the number returned by DATE into a date 
string. This depends on the country code of your computer's operating system. It 
can be altered using: 

OPTION DATE form Z,separator] 

Where form and the resulting date format are as follows: 


form 

Format 

form 

Format 

0 

mmlddlyy 

4 

mm/dd/yyyy 

1 

ddlmmlyy 

5 

ddlmm/yyyy 

2 

yy:mm:dd 

6 

yyyy:mm:dd 

3 

yymmdd 

7 

yyyymmdd 


If the separator is not given, then the separators above are used. If it is given, then 
it must be a string of which the first character is used. The string may be null. 

The format set using OPTION DATE is also assumed when converting a string date 
to a numeric date, using the function DATE. 


Discs 


To change the default drive used by BASIC 2, use DRIVE: 

DRIVE drive 

drive is a string expression, the first character of which is taken as the new drive 
letter. 

Protecting programs 

A program can normally be stopped using Ctrl-C. To stop this having any effect, 
use: 

OPTION RUN 

This provides a useful way to protect a program from accidental pressing of Ctrl-C 
and may help to prevent unauthorised meddling or copying with a program, once it 
has been loaded. 

To restore the normal operation of Ctrl-C use: 

OPTION STOP 



Undefined variables 

BASIC 2 normally allows use of variables even if they have not been assigned a 
value (the value being taken as 0 or according to variable type). To have 
references to such 'uninitialised variables' reported as an error, use: 

OPTION TRAP ON 

Note that references to anything with a storage class (array variables or record 
fields) will still not be reported as errors. 

To return to normal behaviour: 

OPTION TRAP OFF 
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5. MULTI-USER SYSTEMS 




Certain versions of BASIC 2 will allow several users to use the same computer at 
the same time, sharing resources like discs and printers or even data files. This sort 
of system is called a ‘multi-user’ system. 

These versions of BASIC 2 will behave exactly as described in the rest of this guide, 
with the exception of details provided here, concerned with shared access to data 
files. 

By following the guidelines here, you will be able to produce programs that will 
work efficiently on single-user systems and multi-user systems. 

If you do not follow these guidelines, your programs will still work on multi-user 
systems, but will not allow other users to share files while they are using them. 


Locking 

Multi-user systems provide an efficient way of sharing resources, including data 
files. 

However, sharing files in this way can run into problems, when files are being 
altered. This is because while making the changes, the information in the file may 
be inconsistent - if the file is read at this stage by another user, incorrect 
information might be read. 

This is most often the case with keyed access files, where the index file is updated 
separately to the data file. It can however happen with any type of file, if the 
information in it is inter-related in any way. 

To avoid this type of problem, multi-user systems will use a facility known as 
‘locking’, used to stop other programs reading or writing to a file or particular 
records in a file. 

Locking is requested explicitly by using the optional parameter LOCK lock with the 
file handling commands described in previous chapters. On single user BASIC 2 no 
file sharing is allowed, so that multi-user programs can be used with single user 
BASIC 2 without alteration. 

The type of lock required is indicated by an integer expression, lock, as follows: 

lock Effect 

0 no lock or unlocked 

1 read locked 

2 write lock 

If a lock is not specified, the default lock for the operation is applied, as described 
below. 

Locking can be applied to sequential, random and keyed files, and to individual 
records (and their keys) in random and keyed files. 
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Locking random and keyed files 

The lock required for a random or keyed file is specified by each user when opening 
it (and can then only be changed by closing and opening the file again): 

OPEN #stream[qualifier] RANDOM file-name /INDEX index-name] 

/LENGTH record-length] /LOCK lock] 

If a lock is not specified, the file will be opened write-locked. 

The locks which can be attempted are: 

lock Lock name Limitation 

0 Unlocked This will fail if the file is write-locked. 

1 Read-locked This will fail if the file is write-locked. 

2 Write-locked This will fail if the file is already open. 

The lock actually in force on the file is the highest lock that has been successfully 
applied to it. Thus, even if a user has opened the file unlocked, if another user has 
opened or does open it read-locked, the file will be read-locked to all users. 

The current file lock effects what can be done with the file by all users, as follows: 

- an unlocked file can be read or written by any user, subject to any record locks 

- a read-locked file can only be read, by any user 

- a write-locked file can be read or written, but only by the user that opened it 

The file lock applied by a user is released when that user closes the file, so that a 
file might change from read-locked to unlocked if the user that read-locked it closes 
the file. 

(Unlocked files can be record-locked to control access to individual records: see 
below.) 

Locking sequential files 

Opening a sequential file for input, the lock required by each user is specified in the 
command: 

OPEN #stream INPUT file-name /LOCK lock] 

lock must be 1 (read-locked) or 2 (write-locked). If not specified, the file is opened 
read-locked. 

Opening a sequential file for output or appending will write-lock the file: 

OPEN #stream [qualifier] APPEND file-name 
OPEN #stream [qualifier] OUTPUT file-name 

The locks which can be attempted are: 
lock Lock name Limitation 

1 Read-locked This will fail if the file is write-locked. 

2 Write-locked This will fail if the file is already open. 


The current file lock effects what can be done with the file by all users, as follows: 

- a read-locked file can only be read, by any user 

- a write-locked file can be read or written, but only by the user that opened it 

The file lock applied by a user is released when that user closes the file, so that a 
file can be re-opened with a different lock only when all current users have closed it. 

Locking records 

Records in a random or keyed file can be unlocked, read-locked or write-locked, 
similarly to files, by specifying the lock required in the command used to access the 
record, or in a LOCK command. BASIC 2 also enforces temporary locking, to protect 
a record and its keys for the duration of an operation. 

A write-locked file has all of its records implicitly write-locked. A read-locked file 
has all of its records implicitly read-locked. 

Record locks can be temporary (dropped as soon as certain other file access 
command are executed) or permanent (remain in force until explicitly changed by 
the same user, or that user closes the file). 

A record's lock state is determined by the highest lock successfully applied to it. 
The locks which can be attempted are: 


lock Lock name 

0 unlocked 

1 read-locked 

2 write-locked 


Limitation 

fails if record write-locked 
fails if record write-locked 
fails if any other user has locked the record 


The three states allow different operations on the record, as follows: 


• unlocked records cannot be read or written by any user 

• read-locked records and their keys can only be read, not deleted nor changed (noi 
can you add keys for a read-locked record) 

• write-locked records and their keys can be read or written, but only by the user that 
write-locked them 


The following commands all temporarily write-lock the position (record and its keys) 
they are operating on, releasing any other temporary lock for that file applied by that 
user: 

POSITION 

GET 

PUT 

ADDREC 

ADDKEY 

DELKEY 

Any temporary record lock is also released when the user closes the file. 
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To obtain or release a permanent lock, use the LOCK command: 

LOCK #stream [position] LOCK lock 
or LOCK #stream [position], lock 

Alternatively, append the optional /LOCK lock] to any of the aforementioned 
commands. 

A permanent lock can only be released by the user that applied it. specifying a lock 
of 0 (unlocked) or closing the file. 

Recommendations 

The main recommendation is that you should always open files with the lowest level 
of locking that your program needs. 

Random and keyed files are opened write-locked by default. If a program is just 
going to read a file, it should open it read-locked. Even if it is going to change the 
file, it would be friendlier to open the file unlocked and lock records that it wants to 
read or change. 

Sequential files are, by default, opened read-locked (INPUT) or write-locked 
(OUTPUT, APPEND). These default locks are suitable for most processing. 



SELECTOR Commands and Functions 


The SELECTOR command allows BASIC programs to invoke an Item 
Selector* Dialog, and use the result 

The Item Selector Dialog takes two strings as parameters. The first is 
shown as Directory, the second as Selection. The Directory string 
sets both the directory from which the selection is to be made, and which 
files in that directory are eligible. The Selection string is the name of the 
currently selected file. During the dialogue, the user can change either of 
these strings, and then leave the Dialog by 'Ok or 'Cancel* buttons. 

The SELECTOR command takes two string parameters. The first sets the 
initial value of the Directory string, the second the initial value of the 
Selection. Using the 'assigned command' form it is possible to tell 
whether exit from the Dialog was by Ok or Cancel. For example: 

r=SELECTOR " \GMCH\*. TXT", "FREDRICK. TXT" 

will invoke an Item Selector Dialog which initially shows files with type 
TXT in the directory \gmch\ on the current drive. The initial Selection is 
the file fredrick.txt. The variable r will be set to zero if the user 
chooses the Ok exit, and to -1 if Cancel is chosen. 

In order to use the result of the Item Selector Dialog three functions are 
provided - SELPATH$, SELWILD$ and SELFILE$. These functions return 
the current values of string variables built into BASIC: 

SELFELE$ returns the Selection made. 

SELWILD$ returns the last part of the Directory string - the file name portion, which 
may contain ‘wild card' characters to specify which files are eligible for 
selection. 

SELPATH$ returns the first part of the Directory string - the path name portion, 
which specifies the drive and directory in which the selected file resides. 
An error will occur if the directory does not exist. 

The full name of the file selected is, therefore, selpath$+selfxie$. 

The following will use a SELECTOR command to get from the user the 
name of a file, which is then opened for Input: 

r=SELECTOR "\GMCH\*.TXT", "FREDRICK.TXT" 

IF rOO THEM STOP 'STOP if Dialog Canoollod 
OPEN #5 INPUT SELPATH$+SELTILE$ 

When a SELECTOR command is obeyed, the values of the parameters are 
set into the interpreter variables associated with SELPATH$, SELWILDS 
and SELFILE$. The Dialog is then invoked and given the values of these 
variables as its parameters. If the Ok exit is taken, the variables are 
overwritten with the new values set by the user. If the Cancel exit is 
taken, the variables are left unchanged. 






The parameters for the SELECTOR command are, in fact, optional. If a 
parameter is omitted, then the current settings of the appropriate 
interpreter variables are used. Before any SELECTOR command is obeyed 
the path is set to the current directory, the wild part is set to *. * and the 
file selected is set to the null string. 

The full syntax for the SELECTOR command is: 

selector [directory-portion], selection-portion 

or: SELECTOR 

Both parameters are string expressions. If a directory portion ending in a 
\ is given, then *. * is added to it. 

A group of OPTION commands are provided to set the values of the 
various interpreter variables: 

OPTION SELPATH$ string-expression 
OPTION SELWILD$ string-expression 
OPTION SELFILE$ string-expression 

INKEY, INKEY$ and OPTION INKEY$ 

INKEY and INKEYS are functions which return a value which depends on 
the key currently being pressed. If no key is currently being pressed, 
INKEY returns zero and INKEYS the null string. Under DOS, characters are 
represented by an 'extended ASCIT code, each character having a value 
between 0 and 255. Not all keys correspond to a character, and a special 
mechanism is used to return a Trey value* in cases where it does not. 

For extended ASCII characters the function INKEY returns the character 
value, and INKEYS returns a character equivalent to CHRS(INKEY). 

For keys which do not correspond to an extended ASCII value such as 
function keys, INKEY returns 256 + the key value i.e. for a key value n, 
INKEY returns n+256. In this case, INKEYS returns a character selected 
from a special character string (the INKEYS-string). For a key value n, 
INKEYS will return the nth character of the INKEYS-string. If the required 
character is outside the INKEYS-string or has internal code zero, the null 
string will be returned. 

The special INKEYS-string is initially set to 256 characters, all with 
internal code zero. OPTION INKEYS can be used to set the INKEYS-string 
and has the syntax: 

OPTION INKEY$ string 

This has the effect of setting the INKEYS-string to string 



The ALERT command 


Use the ALERT command to display an Alert box and optionally to set a 
value according to which exit button is selected. 

An Alert box consists of tin optional icon, up to five lines of text and up to 
three exit buttons. The box is displayed and then the user can chick on 
one of the exit buttons for the program to continue. One of the exit 
buttons, the default, can be shown with a thick border, and in that case 
pressing the return key is equivalent to clicking on the highlighted 
button. 

The syntax is: 

alert icon-number TEXT string-expressions BUTTON button-specs 

where: icon-numberxs a number from 0 to 3 and governs which icon is displayed - 
0 for no icon, 1 for the Note icon, 2 for the Wait icon and 3 for the Stop icon. 

and string-expressions is up to five strings of text sepatated by commas. These 
correspond to the five lines of text. 

and button-specs is up to three strings of text separated by commas. These 
correspond to the three exit buttons. One string may be proceeded by 
return to indicate that it is the default exit button. 

The ALERT command can be used in an assignment to detect which exit 
button was chosen. It returns value 1,2 or 3. 
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Characters 



Note: not all implementations of GEM will support all these characters. 
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Escape sequences and control codes 

The following escape sequences, based on those obeyed by an industry standard 
text terminal (VT52) will be obeyed when printed in a text or graphics screen. All 
other sequences are ignored. Sequences marked * will only be obeyed in a graphics 
screen; sequences marked ** will only be obeyed in a text screen. 


Sequence 

Effect 

ESC code 

print code, which must be less than 32 

ESC A 

move cursor up 1 line 

ESC B 

move cursor down 1 line 

ESC C 

move cursor forward 1 column 

ESC D 

move cursor backward 1 column 

ESC E 

clear window and move cursor to top left 

ESC F n+32 

set font n * 

ESC H 

move cursor to top left 

ESC I 

move cursor up 1 line, scrolling if necessary 

ESC J 

clear to end of virtual screen** 

ESC K 

clear to end of line** 

ESC L 

insert blank line** 

ESC M 

delete line** 

ESC N 

delete character** 

ESC P n+32 

set point size n* 

ESC W n+32 

set write mode* 

ESC X 32+n/5 

set text angle n * 

ESC Y x+31 y+31 

move cursor to column x, line y 

ESC b c 

set foreground colour 

ESC d 

clear from start of virtual screen to cursor** 

ESC e 

make cursor visible 

ESC f 

make cursor invisible 

ESC j 

save cursor position 

ESC k 

move to saved cursor position 

ESC 1 

clear whole line 

ESC m 

enter lightened mode 

ESC n 

exit lightened mode 

ESC o 

erase from beginning of line to cursor** 

ESC p 

enter reverse video mode 

ESC q 

exit reverse video mode 

ESC r 

enter thickened mode 

ESC s 

enter underlined mode 

ESC t 

exit underlined mode 

ESC u 

exit thickened mode 

ESC v 

wrap at line end 

ESC w 

no wrap at line end 

ESC x 

enter skewed mode 

ESC y 

exit skewed mode 





The following control codes will be obeyed in a text or graphics screen: 


Code 

Name Effect 

7 

BEL 

sound a bleep 

8 

BS 

move cursor left one column 

10 

LF 

move cursor down one line, scrolling if needed 

13 

CR 

move cursor to start of current line 

27 

ESC 

start escape sequence 

127 

DEL 

delete character 


CHARACTER 

CODES 
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PLOT 250;260 SIZE 4 MARKER 3 


UNE 100;100,100,400, 400;100 STYLE 2 END 1 


BOX 100;100, 300, 300 


BOX 100;100, 300, 300 ROUNDED RLL WTTH 16 


SHAPE 100;100,100;300,300;100,300;300 RLL WTTH 8 







CIRCLE 260:250, 225 


CIRCLE 260;250, 225 PART PI/2, 3*PV2 


PE 250:250, 226, PI/3, 2*PI 


ELLIPSE 250;250, 200,1.25 


ELLIPSE 250,250, 200,1.25 PART PI/2, 3*PI/2 


ELLIPTICAL PIE 250;250, 225, 1.25, PI/3. 2*P1 



ymouse 
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Default Text Style 


FONT 

1 

System (for screen) 

First (for other devices) 

EFFECTS 

0.0 

All off 

POINTS 

10 

10 point (if available) 

COLOUR 

1 

black 

ANGLE 

0 

Horizontal 

WRAP 

1 

on 

MARGIN 

0 


ZONE 

18 


MODE 

1 

Replace write mode 


Default Graphics Style 


CURSOR 

1 

Crosshair 

COLOUR 

1 

Black 

MARKER 

1 

Point 

MARKER SIZE 

1 

Smallest 

LINE STYLE 

1 

Solid 

LINE WIDTH 

1 

1 pixel 

FILL STYLE 

8 

Solid 

START STYLE 
END STYLE 

0 

Square end 

MODE 

1 

Replace write mode 
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APPENDIX 111:2. MENUS AND FUNCTION KEYS 




This is a reference section giving a summary of the options available 
through menus or by pressing function keys while you are using BASIC 2. 

The File menu 

Load... - Loads a stored BASIC program into memory, replacing any program 
you have been running or editing so far. 

Selecting this option brings the Item Selector Dialog box onto the screen. Use this to 
pick out the file holding the program you want to run or edit (see Part 0. Section 
2 . 11 ). 

Save... - Saves your current program as an ASCII text file. 

Selecting this option brings the Item Selector Dialog box onto the screen. Use this to 
specify the file you want to store your program in (see Part n. Section 2.11). 

Quit - Leave BASIC 2 and return to the GEM Desktop. 

The Program menu 

Run - Runs your current program. 

You can also run this progr am eit her by typing the command RUN in the Dialogue 
window or by pressing the I F9 I key. 

Stop - Stops the program that is currently running. 

You can also stop the program either by typing the command STOP in the Dialogue 
window or by pressing Ctrl-C 

Continue - Makes the program resume at the point it was stopped. 

You can also continue running the program by typing the command CONT in the 
Dialogue window or by pressing the I F7 | key. 

Edi t - Goes into the Editor to edit the current program. 

You can also do this by: 

- pressing I fio | 

- clicking in the Edit window 

- typing the command EDIT in the Dialogue window 

- selecting the Edit option in the Edit menu 

If you are already in the Editor, the option becomes Exit Edit. Selecting this 
option or pressing I fio I then leaves the Editor and returns you to the Dialogue 
window. 

List - Lists the current program on your printer. 

New - Clears the current program from memory so that you can start preparing a 
new program. 

The current program isn’t saved before it is erased from memory. 


Run 

FT 

Stop 

Ctrl-C 

Continue 

*7 

"Edit'*'"" 

—fir 

List 


New 


Angles in ■■■ 


Load ... 

Save ,,, 

Quit 
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Angles in ... - Selects whether angles are assumed to be in degrees or in 
radians. 

Selecting this option brings a Dialog box onto the screen, with Radians and Degrees 
as options. The current selection is highlighted. 

The Edit menu 

Edit - Goes into the Editor to edit the current program. 

You can al so do this by: 

- pressing I fio| 

- clicking in the Edit window 

- typing the command EDIT in the Dialogue window 

- selecting the Edit option in the Program menu 

If you are already in the Editor, the option becomes Exit Edit. Selecting this 
option or pressing I fio| then leaves the Editor and returns you to the Dialogue 
window. 

Start area - Marks the start of a section of program you want to copy, move or 
delete. 

This action marks one end of the section. The other end can be either before or after 
the Start end. 

You can also mark the start of the section by pressing I fi 1 

End area - Marks the end of the section of program you want to copy, move or 
delete. 

The section of program you have marked becomes highlighted and the cursor is 
changed in style to remind you that a section of program is marked ready to move, 
copy or delete. 

You can also mark the end of the section by pressing I fi I 

Cancel area - Cancels the marking of a section of program. 

If you wish you can stop marking the section after just positioning one end. The 
section of program is left in its current position. 

You can also stop marking the section by pressing I F 2 I 

Copy area - Inserts a copy of a marked section of the program at the cursor 
position. 

You can also copy the program segment by pressing I F3 I . The original program 
segment is unaffected. 

Hove area - Moves a marked section of program, removing it from its current 
position and inserting it at the cursor position. 

You can also move the program segment by pressing I F4 I 

Delete area - Removes a marked section of the program. 

You can also delete the program segment by pressing I fs I 

Insert On/Off - Toggles whether what you type at the keyboard is inserted into 
your program or overwrites the existing program lines. 






















If program lines are currently overwritten by anything you type, selecting this option 
will cause what you type to be inserted and vice versa. 

You can also toggle this action by pressing I in« I 

Renumber... - updates the line numbers used in your program and puts them 
into the ascending sequence you specify. 

Selecting this option brings a Dialog box onto the screen. This gives the current 
choice of first line number and the step by which line numbers should be 
incremented. You can change either or both of these settings (see Part D. Section 
2 10) before selecting the (OK) exit option. The program is then renumbered. 

Note: Only the lines which have a line number will be renumbered. 

The Fonts menu 

This menu is in three sections. Selections are made in each section by separate 
clicks of the lefthand mouse button. The small arrows mark the current selections. 
There can only be one arrow in each of the top two sections, but you can have any 
number of arrows in the bottom section. 

When you click on an option in either of the top two sections, the appropriate arrow 
moves to your new selection. If you click on a option in the bottom section, it will 
become selected if it wasn’t selected before but de-selected if it was selected 
before. As you make each selection. GEM will automatically close up the menu: 
bring the menu onto the screen again to make any further selections you want. 

The character style, size and emphasis set in the menu will be used as the default 
for all future text to be displayed on the default screen until you make another 
selection or reset the BASIC by using a CLS RESET command. 

Top section 

Listed in the top section of the menu are the character styles that are available for 
writing text on the default screen. 

System font is always available and is used on both text screens (such as Results-2) 
and graphics screens (such as Results-1). Swiss and Dutch, for example, are the 
names of the fonts listed in your computer's ASSIGN.SYS file. The Loadable option 
(if included) just indicates that BASIC 2 can work with another character style if this 
were to be loaded through the ASSIGN.SYS file. These other fonts are only available 
if your default screen is a graphics screen: they are not available on a text screen. 

The numbers beside the font names are the numbers used by certain commands 
and functions to identify a particular character style. 

Middle section 

Listed in the middle section of the menu are the sizes of characters that you can 
use. The sizes depend on which .FNT files are listed in your computer's 
ASSIGN.SYS file. Each of these files contains details of characters of one particular 
size, which can also be used to generate double-size characters. 

If the size is available, it is written in normal text. If the size isn't available, it is 
written in lightened text. 


► 1 System 

2 Loadable 

3 Loadable 

4 Loadable 

7 Point 

8 Point 

► 10 Point 

12 Point 
14 Point 

16 Point 


18 Point 
20 Point 

24 Point 
28 Point 
36 Point 
72 Point 
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All the options are written in lightened text when the default screen is a text screen 
because only one text size can be used. The different text sizes can only be used on 
graphics screens. 

Bottom section 

The bottom section lists the different character effects (or emphases) that can be 
applied to the text. Again these are only available when the default screen is a 
graphics screen. 

Thickened - Emboldens the text. 

Lightened - Lightens the text. 

Skewed - Makes the characters slant forward, giving an italic style of text. 
Underlined - Underlines the text. 

Clicking on an option that is currently selected de-selects that option. 

The Colours menu 

The Colours menus lists all the different colours that are available for writing text 
and drawing graphics. If you have a monochrome monitor, you will see the different 
intensities that are available 

The colours set in the menu are used as the default for all following text and 
graphics until you make a different selection or reset BASIC by using a CLS RESET 
command. 

The menu is in two sections because the colours for text and graphics can be 
chosen independently. Small arrows mark the current selections 

The numbers beside the colours are the numbers used by certain commands and 
functions to identify a particular colour. 


Text 

0 8 

2™ 10 

3 III: 11 

4 Ur- 12 

5 •m 13 

6 14 

7 15 

m 

gets 

Graphics 


0 8 


► i m 91 

m 

2 101 


3 •:•!■■! i 11 1 


4 121 


5 mi 13 1 


6 141 


7 151 
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The Patterns menu 



The Lines menu 


The Patterns menu lists all the different patterns that are available for 
filling shapes on a graphics screen. A small arrow marks the ament 
selection. These patterns will be drawn in the current graphics colour 
when you use them to fill an area of the screen. 

No graphics patterns can be used on a text screen. 

The pattern set in the menu is used as the default pattern to fill all the 
shapes you ask to fill until you make another selection or reset the 
BASIC using a CLS RESET command. 

The numbers beside the patterns are the numbers used by certain 
commands and functions to identify a particular pattern. 



The Lines menu lists the various styles, thicknesses and end-styles available for 
drawing lines on graphics screens. No lines can be drawn on text screens. 

The menu is in three sections, with a small arrow marking the selection in each 
section Selections in each section are made by separate clicks on the lefthand 
mouse button. As you make each selection, GEM automatically closes up the menu: 
bring the menu onto the screen again if you want to make another selection. 

The top section shows the six line styles; the middle section shows the four 
different thicknesses of line you can use; the bottom section shows on the left the 
three end-styles available for the start of the line and. on the right, the three 
end-styles available for the end of the line. The numbers are those used by certain 
commands and functions to identify particular line styles. 

The style, thickness and end-styles set in the menu will be used as the default for 
any line that is drawn on the screen until a different selection is made or BASIC is 
reset using a CLS RESET command. 

Note: If you select one of the thicker line thicknesses, you may be limited to just 
the 'plain line' line-style. 
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The Windows menu 


Show Results-1 
Hide Results-1 

**Show Results-2 
Hide Results-2 

Show Edit 
Hide Edit 

Show Dialogue 
Hide Dialogue 


The Windowns menu is used to open or close the windows on the monitor screen. 

If a window is open on the monitor screen, the option Hide window-name will be 
available: clicking on this option will close the window. This doesn’t, of course, stop 
your program sending output to the virtual screen associated with the window: it 
just stops this information being displayed on the monitor. 

The other options in the menu have the form Show window-name. If the window is 
closed, clicking on this option will open the window, giving it the same size and 
position as it had when it was closed. In all cases, it makes the chosen window the 
active window. 


The BASIC 2 menu 


This is identical to the DESKTOP menu available while you are using the GEM 
Desktop, except that the information about the GEM Desktop has been replaced by 
information about the BASIC 2 program. 

The Desk Accessories - Snapshot, the Calculator, the Clock and the Print Spooler - 
may all be used as described in your GEM user guide. 


The Function keys 

DO Marks the start of a section of program you w ant to copy, move or delete. 
If the start has already been marked, pressing I fi | marks the end of the 
section. The End marker can be either before or after the Start marker. 

I F2 | Stops marking a section of program. If you wish you can stop marking the 
section after just positioning one end. The section of program is left in its 
current position. 

I~ra~l Inserts a copy of a marked section of the program at the cursor position. 
The original program segment is unaffected. 

QO Moves a marked section of program, removing it from its current position 
and inserting it at the cursor position. 

I~F5~1 Removes a marked section of the program. 

I F7 | Makes the program resume at the point it was stopped. 

I F9 I Runs your current program. 

r~Fio~i Goes into the Editor to edit the current program. If you are already in the 
Editor, pressing I fio I leaves the Editor and returns you to the Dialogue 
window. 
















APPENDIX IV: BASIC 2 KEYWORDS 


The following are BASIC 2 keywords. They are reserved and cannot be used as variable names. 

ABS, ACOS, ADDKEY, ADDREC, ADJUST. ALERT. AND. ANGLE. APPEND. ARC. AS. ASC. ASIN. AT. 
ATAN. ATAN2, ATN 

BINS, BOL, BOS, BOX, BUTTON, BYTE 

CASE CD CEILING, CEND, CHDIR, CHDIRS, CHRS, CINT, CIRCLE, CLEAR, CLOSE, CLS, COLOR, 
COLOUR. CONSOLIDATE. CONT. COS, CURRENCYS. CURSOR 

DATA DATE DATES. DECS, DECIMAL, DEF, DEG, DEGREES, DEL. DELETE. DELKEY, DEVICE. DIM, 
DIMENSIONS.' DIR. DISPLAY. DISTANCE. DRIVE 

EDIT, EFFECTS, ELLIPSE. ELLIPTICAL, ELSE, END. EOF. EOL. EOS, ERASE. ERR. ERROR. ERRORS. EXP. 
EXTENT 

FALSE FD FEED, FEND, FI, FILES, FILL, FINDS. FINDDIRS, FIX, FIXED. FLEXIBLE. FLOOD. FLOOR. FN. 
FONT, FONTS, FOR, FORWARD, FRAC. FRE. FULL. FUNC 

GET. GOSUB, GOTO, GRAPHICS 

HEADING, HEXS 

IF. INDEX. INFORMATION. INKEY, INKEYS. INPUT. INPUTS. INSERT. INSTR. INT. INTEGER 
KEY, KEYS, KEYSPEC. KILL 

LABEL LEFT. LEFTS, LEN, LENGTH. LET. LINE, LOC, LOCAL. LOCATE. LOCK. LOF. LOG. LOGIO. 
LOWER. LOWERS, LPRINT, LSET, LT 

MARGIN. MARKER, MAX. MAXIMUM. MIN. MINIMUM. MD, MIDS, MKDIR. MOD. MODE. MOUSE. MOV" 
NAME, NEW, NEXT, NOT 

OFF. OLD. ON, ONLY, OPEN, OPTION, OR, ORIGIN, OSERR, OUTPUT 

PART, PEND, PI. PIE. PLACE. PLOT. POINT. POINTS. POINTSIZE, POS. POSITION. POSITIONS. PRINT, 
PROC'. PROMPT. PUT 

QUIT 

RAD RADIANS RANDOM. RANDOMIZE, RD, READ, RECORD. REM. REN. REPEAT. REPOSITION. RESET. 
RESTORE, RESUME. RETURN. RIGHT, RIGHTS, RMDIR, RND. ROUND. ROUNDED. RSET. RT. RUN 

SCREEN SCROLL, SELECT, SELECTOR. SELFILES, SELPATHS. SELW1LDS, SET. SGN, SHAPE, SIN. SIZE. 
SPACE, SQR. START, STEP, STOP. STRS. STREAM. STRINGS, STYLE. SWAP. SYSTEM 

TAB, TAN. TEST, TEXT, THEN. TIME, TIMES. TITLE. TO. TOWARD. TRAP. TRUE. TRUNC. TYPE 

UBYTE. UNIQUE. UNIT, UNTIL. UPDATE. UPPER. UPPERS. USER. USING. UWORD 

VAL. VERSION. VPOS 

WEND, WHILE. WHOLES. WIDTH. WINDOW. WITH. WORD. WRAP 

XACTUAL, XBAR, XCELL, XDEVICE. XMETRES. XMOUSE. XOR. XPDCEL. XPLACE, XPOS. XSCROLL. 
XUSABLE, XVIRTUAL, XWINDOW 

YACTUAL. YASPECT. YBAR. YCELL, YDEVICE. YMETRES. YMOUSE, YPIXEL. YPLACE. YPOS. YSCROLL, 
YUSABLE. YVIRTUAL, YWINDOW 

ZONE 


219 


IV: BASIC2 
KEYWORDS 
















Appendix V: Syntax Summary 



This appendix lists the commands and functions used in BASIC 2. It is just a 
summary, you should use the main part of this manual for details of the use of the 
commands and functions. A full reference manual for Locomotive BASIC 2 is also 
available - 'Locomotive BASIC 2 Reference Manual'. 

Metalanguage 

In order to describe commands and their parameters a simple metalanguage is used. 
The form of each command is described as it appears when entered, with any 
variable or optional parts shown by 'place-holders' which refer to a concept defined 
elsewhere. 

A concept is represented by its name shown in light italic type. For example, in 
various places an expression yielding a numeric value is required, this is represented 
by: 

numeric-expression 

Anything shown in a bold computer style type is required as given. For example, 
the STOP command takes the form: 

STOP 

Where there is an optional part in a definition, the optional part is enclosed in 
slanting square brackets. For example, if a numeric expression were to be optional 
then it would appear: 

[numeric-expression] 

If an optional part may be repeated (so may appear any number of times, including 
none at all) an asterisk is appended after the closing square bracket. For example, a 
string of digits, requiring at least one digit, would appear: 

digit [digit]' 

In many places a list of objects separated by commas is used. Such lists are 
expressed in a special form, which is best illustrated by example, thus: 

list of: expression is: expression [, expression]' 
list of: [#]number is: [#]number[, [#Jnumber]' 

Note that the list may be a single object. If the list contains more than one object, 
then each additional object must be preceded by a comma. 

Place-holders are normally self explanatory, either specifying the particular kind of 
information (eg. string-expression) or the use to which the information will be put 
(eg. colour). In this second case, the required value is a numeric-expression. In 
addition, the following special place holders are used: 

filename 

The rest of the line is taken to be a collection of characters which will be recognised 
as a file name by the host operating system. BASIC forces lower case characters to 
their upper case equivalents before presenting the name to the system. 



\/ SYNTAX SUMMARY 




filename-expression 

A string-expression whose value is a valid file name. 
format-template 

A string-expression which is a restricted form of PRINT USING string. 
location 

A label or integer-constant 
logical-expression 

BASIC does not support a separate boolean type. Integer value 0 is treated as False, 
and any other Integer value as True. A logical-expression is, therefore, ari 
integer-expression by another name. Note that TRUE, FALSE, ON and OFF can be 
used and have their usual meanings. 

position 

NEXT, AT position-string, or KEY key-number /INDEX index] 
prompt 

string-constant or PROMPT string-expression 

The commands and functions in alphabetic order. 

Note: Throughout, COLOR can be used as a synonym for COLOUR and for clarity points 
are expressed as x;y rather than the full [x][;y], 

ABS function 

Return the absolute value of a given value. 

ABS ( numeric-expression ) 

ACOS function 

Arc-cosine: Return the angle of which the cosine is the given value. 

ACOS ( numeric-expression ) 

ADDKEY command 

Add a new key for an existing record in a keyed file. 

ADDKEY #stream KEY expression /INDEX index-number] /LOCK lock] 

ADDREC command 

Add a new record and key to a keyed file. 

ADDREC #stream, string-expression KEY expression 
/INDEX index-number] /LOCK lock] 





ALERT command 

Display an Alert Box on the screen. 

ALERT icon-number TEXT string-expression ], string-expression 

[, string-expression (, string-expression (, string-expression]]]] 
BUTTON button-spec],button-spec],button-spec]] 
where button-spec is /RETURN ] string-expression 

AND operator 

ASC function 

Return ASCII value of given character. 

AS C ( string-expression ) 

ASIN function 

Arc-sine: Return the angle of which the sine is the given value. 

ASIN ( numeric-expression ) 

ATAN function 

ATN Arc-tangent: Return the angle of which the tangent is the given value. 

ATAN ( numeric-expression ) 

ATN ( numeric-expression ) 

ATAN2 function 

The bearing of a point (x;y) from the origin. 

ATAN2 (x,y) 

BINS function 

Return a string of binary digits representing the given value. 

BINS ( integer-expression[, field-size]) 
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BOX command 
Draw a box. 

BOX [if stream,]x-, y, width, height 

/rounded; 

/FILL /only; /WITH fill-style]] 

/WIDTH line-width] 

/STYLE line-style] 

/COLOUR colour] 

/MODE write-mode] 

BUTTON function 

Return state of given mouse button. 

BUTTON [(button)] 

CD command 

Change directory. 

CD directory-name 

CEILING function 

Return the given value rounded to an integer. Rounds towards + infinity. 
CEILING (.numeric-expression) 

CHDIR command 

Change directory 
CHDIR string-expression 

CHDIRS function 

Return the current directory for the given drive. 

CHDIR$ [(drive-string)] 

CHR$ function 

Return character with given ASCII value. 

CHR$ (integer-expression) 

CWT function 

Return value rounded to nearest 32 bit signed integer. 

CINT (numeric-expression) 




CIRCLE command 


Draw a circle, centre at point (x;y). 

CIRCLE /# stream,] x;y,radius 

/PART start-angle,end-angle] 

/START end-style] /END end-style] 

/FILL /ONLY/ /WITH till-style]] 

/WIDTH line-width] 

/STYLE line-style] 

/COLOUR colour] 

/MODE write-mode] 

CLEAR command 

Clear all variables and close all file streams. 

CLEAR 

CLEAR RESET command 

Clear all variables and close all file streams. Reset all streams, windows etc to initial 
state. 

CLEAR RESET 

CLOSE command 

Close one or more files. 

CLOSE /list of: #stream] 

CLOSE WINDOW command 

Close a particular window (eg. Dialogue or Edit). 

CLOSE WINDOW number 

CLS command 

Clear a virtual screen and reset cursor position. If RESET is specified, also reset text 
and graphics options (eg. text colour). 

CLS [#stream] /RESET/ 

CONSOLIDATE command 

Mark keyed file as consistent. 

CONSOLIDATE <#sfream) 

CONT command 

Continue after Ctrl-C or STOP. 

CONT 

COS function 

Return the cosine of the given angle. 

COS ( numeric-expression ) 


ut 
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CURRENCY) function 

Return current currency string. 

CURRENCY) 

DATA command 

Declare constant data. 

DATA list of: constant 

DATE function 

• Return the date in days since 31st December 1899. 

DATE 

• Return the given date in days since 31st December 1899. 

DATE ( date-string ) 

DATE) function 

• Return the date as a string in the current form. 

DATE) 

• Return the given number of days since 31st December 1899 as a date string in the 
current form. 

DATE)( date-in-days ) 

DEO function 

Return the formatted string representation of the given value. 

DEC) ( numeric-expression, format-template ) 

DEF command 

Define an expression function. 

DEF fHname[( formal-parameters) ] = expression 

DEG function 

Return the given angle converted from radians to degrees. 

DEG ( numeric-expression ) 

DEL command 
Delete files. 

DEL filename 

DELKEY command 

Delete a key for a record in a keyed file. 

DELKEY #stream [,position] /LOCK lock] 






DIM command 

Declare array dimensions. 

DIM list of: subscripted-variable 

DIMENSIONS function 

Return the number of dimensions in the given array. 
DIMENSIONS ( array-namet )) 

DIR command 

List the directory in the Dialogue window. 

DIR (filename] 


DISPLAY command 

Display contents of a file. 

DISPLAY [#stream] string-expression 

DISTANCE function 

Return the distance of point (x;y) from cursor position. 
DISTANCE ( [#slream,]x; y) 

DRIVE command 

Set the default disc drive. 

DRIVE string-expression 

EDIT command 

Enter editing state. 

EDIT 


ELLIPSE command 

Draw an ellipse, centre (x;y). 

ELLIPSE (if stream, ]x; y,radius,aspect 
/PART start-angle,end-angle] 
/START end-style] /END end-style] 
/FILL /only; /WITH fill-style]] 
/WIDTH line-width] 

/STYLE line-style] 

/COLOUR colour] 

/MODE write-mode] 




ELLIPTICAL PIE command 

Draw a segment of an ellipse centre (x;y). 

ELLIPTICAL PIE [#stream,]x;y,radius,aspect,start-angle,end-angle 
/FILL /ONLY/ /WITH fill-style]] 

/WIDTH line-width] 

/STYLE line-style] 

/COLOUR colour] 

/MODE write-mode] 

ELSE command (see IF) 

END command 

End of program. 

END 

EOF function 

Return result of end of file test for the given stream. 

EOF (# stream) 

ERASE command (synonym for DEL) 

ERR function 

Return Error Number. 

ERR 

ERROR command 

Cause Error action to be taken. 

ERROR integer-expression 

ERRORS function 

Return the error message for the given error number. 

ERRORS ( error-number ) 

EXP function 

Return exponential of numeric value. 

EXP ( numeric-expression ) 

EXTENT function 

Return the distance in user coordinates moved by an equivalent PRINT command. 
EXTENT (/# stream] [print-functions] print-string ) 

FALSE value 

FD command (synonym for FORWARD) 






FILES command 

List the directory on the default or given stream. 

FILES [#stream,] [filename-expression] 

FINDDIR$ function 

Look for a given directory and return its exart name. 

FINODIRS ( directory-name-expression [,ordinal]) 

FINDS function 

Look for given file and return its exact filename. 

FINDS ( filename-expression[,ordinal']) 

FIX function (also called TRUNC) 

Return the given number rounded to an integer. (Rounding is towards zero) 

FIX (.numeric-expression) 

FLOOD command 

Flood-fill a bounded area containing the point (x;y). 

FLOOD [#stream,] x;y [, limit] 

/COLOUR colour] 

/MODE write-mode] 

/FILL WITH fill-style] 

FLOOR function (see INT) 

FONTS function 

Return the name of the font corresponding to a font number. 

FONTS ([#stream,] font) 

FOR command 

Start FOR loop. 

FOR simple-variable = start TO end /STEP step-size] 

FORWARD command 

Move turtle forward, drawing a line unless MOVE is specified. 

/MOVE/ FORWARD /# stream,] distance 
/WIDTH line-width] 

/STYLE line-style] 

/COLOUR colour] 

/MODE write-mode] 

/START end-style] /END end-style] 
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FRAC function 

Returns the fractional part of the given number. 

FRAC (.numeric-expression) 

FRE function 

Returns the amount of free space. 

FRE 

GET command 

Get a record from random or keyed file. 

GET # stream, string-variable [position] /LOCK lock] 

GOSUB command 

Call a subroutine. 

GOSUB location 

GOTO command 

Go to a line. 

GOTO location 

GRAPHICS command 

Change the current graphics style. 

GRAPHICS /# stream,] 

/CURSOR integer-expression] 

/COLOUR colour] 

/MARKER SIZE size] 

/MARKER marker-style] 

//LINE/ WIDTH line-width] 

//LINE/ STYLE line-style] 

/FILL /STYLE/ /WITH/ fill-style] 

//LINE/ START end-style] 

//LINE/ END end-style] 

/MODE write-mode] 

GRAPHICS UPDATE command 

Ensure any pending commands are carried out on a printer or plotter stream. 

GRAPHICS [#stream,] UPDATE /NEW/ 

HEADING function 

Return the current heading (angle) of the turtle. 

HEADING /(# stream )/ 






HEXS function 

Return a string of hexadecimal digits representing the given value. 

HEXS ( integer-expression[, field-size)) 

IF command 

To conditionally execute statements. 

IF logical-expression THEN option-part /ELSE option-part] 
or IF logical-expression GOTO line-number /ELSE option-part] 

INKEY function 

Returns the equivalent value if a key has been typed at the keyboard. 

INKEY 

INKEYS function 

Returns the equivalent character if a key has been typed at the keyboard. 

INKEYS 

INPUT command 

On prompt, input data from console. 

INPUT [#stream,] /AT (x;y )] [;][prompt;Jlist of: variable];] 
or INPUT [#stream,] /AT (x;y)/ [;] [prompt, ]list of: variable};] 

INPUTS function 

Input a fixed length string. 

INPUTS (/# stream,] integer-expression) 

INSTR function 

Return the position of the substring in the given string. 

INSTR ( [integer-expression,}searched-string,searched-for-string) 

INT function 

Return the given value rounded to an integer. Rounding is towards -infinity, (also 
called FLOOR) 

INT ( numeric-expression) 

KEY function 

KEYS 

Return current key value in keyed file. 

KEY ( #stream) 

KEYS (.#stream) 
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KEYSPEC command 

Define an index for a keyed file. 

KEYSPEC #stream [,] INDEX numeric-expression [key-type) 
/UNIQUE logical-expression] 

where key-type may be any of: 

BYTE, UBYTE, WORD. UWORD, INTEGER or FIXED length 

KILL command 

Kill (erase) file. 

KILL filename-expression 

LABEL command 

Give a name to a line. 

LABEL name 

LEFT command (also known as LT) 

Turn turtle left through a given angle. 

LEFT [#stream,jangle 

LEFTS function 

Return left hand part of the given string. 

LEFTS ( string-expression,integer-expression ) 

LEN function 

Return the length of the given string. 

LEN < string-expression ) 

LET command 

Preface an assignment. 

LET variable = expression 

LINE command 

Draw series of straight lines through a list of points. 

LINE [#stream,] list of: x;y 

/START end-style] /END end-style] 

/WIDTH line-width] 

/STYLE line-style) 

/COLOUR colour] 

/MODE write-mode] 

LINE INPUT command 

Input complete line from console. 





raff 

LINE INPUT [#stream f ] /AT (x;y)] [;][prompt; ]string-variable[; ] 
or LINE INPUT [#stream,] /AT (x;y)/ /; ][prompt,]string-variable[;] 

LOC function 

Return the record number of current location in the given file. 

LOC (#stream) 

LOCATE command 

Move cursor to given line and column of virtual screen. 

LOCATE [#stream,][column ]/; line] 

LOCK command 

Change a record lock. 

LOCK #stream [POSITION] /LOCK lock] 

LOCK #stream [POSITION] [, lock] 

LOF function 

Return the length of the given file. 

LOF (# stream) 

LOG function 

Return the natural logarithm of the given value. 

LOG (.numeric-expression) 

LOGIO function 

Return the logarithm, base 10. of the given value. 

LOG 10 (numeric-expression) 

LOWER function 

Return the lower bound of the given array dimension. 

LOWER ( array-name() [, integer-expression]) 

LOWERS function 

Return the given string converted to lower case. 

LOWERS (string-expression) 

LPRINT command 

Print to the Line Printer. (Identical to PRINT with default stream #0) 

LSET command 

Set one string to another, left justified. 

LSET string-variable = string-expression 
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LT command (synonym for LEFT) 

MAX function 

Returns the maximum value of the given list. 

MAX (//sf of: numeric-expression) 

MD command 

Create a directory. 

MD directory-name 

M1D$ command and function 

Replace or return part of a string. 

MID$ (string,start-position[,substring-length]) 

For MID$ as a command string must be a string-variable, part of which is to be 
altered. For MID$ as a function, string is a string-expression, part of which will be 
returned as the function's value. 

MIN function 

Return the minimum value of the given list. 

MIN (list of: numeric-expression) 

MKDIR command 

Create a directory. 

MKDIR string-expression 

MOD operator 

MOVE command 

Move the cursor to point (x;y) in a graphics screen. 

MOVE [# stream,] x;y 

MOVE FORWARD command (see FORWARD) 

Move the turtle forwards without drawing a line. 

NAME command 

Rename a disc file. 

NAME filename-expression AS filename-expression 
NEW command 

Prepare to enter new program. Remove any current program from memory. 

NEW 





I 


NEXT command 

Step FOR loop control variable to next value. 

NEXT [list of: variable] 

NOT operator 

OFF value 

ON value 

ON ERROR GOTO command 

Enable or disable error trap. 

ON ERROR GOTO location 
ON ERROR GOTO 0 

ON GOSUB commands 

u GOSUB or GOTO one of list of locations depending on given value 

ON integer-expression GOSUB list of: location 
ON integer-expression GOTO list of: location 

OPEN command 

• Open a file for serial input. 

OPEN #sf ream INPUT filename /LOCK lock] 

• Open a file for serial output. 

OPEN # stream [qualifier] APPEND filename 
OPEN #stream [qualifier] OUTPUT filename 

where qualifier is NEW or OLD 

• Open a file for random or keyed access. 

OPEN #stream [qualifier] RANDOM filename /INDEX filename] 
/LENGTH record-length] /LOCK lock] 

where qualifier is NEW or OLD 

• Open a window, printer or graphics device. 

OPEN # stream WINDOW integer-expression 
OPEN #stream PRINT integer-expression 
OPEN # stream DEVICE integer-expression 

OPTION command 

CURRENCY) g et t ^ e curiency symbol for use with $ in PRINT USING. 

OPTION CURRENCY) string-expression 
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OPTION DATE command 

Set the form of a date string. 

OPTION DATE form [,separator-string] 

OPTION DECIMAL command 

Set the decimal point and thousands separator for use in PRINT USING. 
OPTION DECIMAL string-expression,string-expression 

OPTION DEGREES command 

Set trigonometrical values in BASIC 2 to work in degrees. 

OPTION DEGREES 

OPTION INKEYS command 

Set translations for special keys for INKEYS. 

OPTION INKEYS string-expression 

OPTION RADIANS command 

Set trigonometrical values in BASIC 2 to work in radians. 

OPTION RADIANS 

OPTION RUN command 

Prevent a BASIC program from being stopped. 

OPTION RUN 

OPTION SELFILES command 

OPTION SELPATHS command 

OPTION SELWILDS command 

Set the parameters of a file selector 

OPTION SELFILES string 
OPTION SELPATHS string 
OPTION SELWILDS string 

OPTION STOP command 

Reverse the effect of OPTION RUN. 

OPTION STOP 

OPTION TRAP command 

Turn on or off trapping of undefined values. 

OPTION TRAP logical-expression 


OR operator 





OSERR function 

Return operating system dependent error indication. 

OSERR 

PI function 

Return the value of ir. 

PI 

PIE command 

Draw a pie slice, point at (x;y). 

PIE [# stream,] x; y, radius, start-angle, end-angle 
/FILL /ONLY/ /WITH fill-style]] 

/WIDTH line-width] 

/STYLE line-style] 

/COLOUR colour] 

/MODE write-mode] 

PLOT command 

Plot a list of points (x;y). 

PLOT [#stream,] list of: x;y 
/MARKER marker-type] 

/SIZE marker-size] 

/COLOUR colour] 

/MODE write-mode] 

POINT command 

Set the turtle to point in the given direction. 

POINT /# stream,] angle 

POINTSIZE function 

Return the nearest smaller point size of the given font to that requested. 

POINTSIZE ([# stream,] font, point-size) 

POS function 

Return the current character position of the cursor. 

POS(#sfream) 

POSITION command 

Set current position in a random or keyed file. 

POSITION # stream, position /LOCK lock] 

POSITIONS function 

Return the position-string of the current position in a random or keyed file. 

POSITIONS (^stream) 
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PRINT command 

Print to a stream (initially defaults to RESULTS1). 

PRINT [#stream,] [print-list][using-clause][separator] 

where print-list is a list of print-item separated by , or 
and print-item can be any of: 

expression 
AT (.column;line) 

COLOUR (colour) 

COLOR (colour) 

EFFECTS ( effects-bits[,effects-bits]) 

TAB ( integer-expression) 

FONT (font) 

POINTS (point-size) 

ANGLE (angle-in-degrees) 

MODE (write-mode) 

MARGIN (position) 

ADJUST (point-size) 

ZONE (zone-width) 

PUT command 

Put data to random access or keyed access file. 

PUT #stream, string-expression [position] /LOCK lock] 

QUIT command (synonym for SYSTEM) 

RAD function 

Return angle in radians. 

RAD (numeric-expression) 

RANDOMIZE command 

Randomise the current random number seed. 

RANDOMIZE [integer-expression] 

RD command 

Remove (delete) the given directory. 

RD directory-name 

READ command 

Read from DATA statements. 

READ list of: variable 

RECORD command 

Define a record structure for use with strings. 

RECORD record-name; list of: field 





REM command 

Remark, the rest of the line is ignored by BASIC. 

REM rest-of-line 

A single quote character in a line (not in a string) is equivalent to :REM. and may 
also prefix comment text, except in: DATA, DEL. DIR. ERASE, REN and TYPE 
commands 

REN command 

Rename disc file. 

REN old-name separator new-name 

where separator is semi-colon, space, comma or equals. 

REPEAT UNTIL command 

Repeat a sequence of commands until the condition given on the UNTIL command 
is true. 

REPEAT 

UNTIL logical-expression 

REPOSITION command 

Change the current position to another position for the current record. 

REPOSITION #stream, position /LOCK lock] 

RESET command 

Reset file system to allow discs to be changed. 

RESET 

RESTORE command 

Restore the pointer into DATA list. 

RESTORE [location] 

RESUME command 

Resume execution after processing an error. 

RESUME 

or RESUME location 

or RESUME NEXT 

RETURN command 

Return from a subroutine. 

RETURN 
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RIGHT command 

Turn turtle through an angle to its right (clockwise). (Also known as RT) 

RIGHT [#stream,] angle 

RIGHTS function 

Return the right hand part of the given string. 

RIGHTS ( string-expression,integer-expression) 

RMDIR command 

Remove (delete) the given directory. 

RMDIR string-expression 

RND function 

Return the next (pseudo)random number. 

RND [(.integer-expression)] 

ROUND function 

Return the given value rounded to the given number of decimal places or power of 
ten. 

ROUND (numeric-expression [,decimals]) 

RSET command 

Set one string to another, right justified. 

RSET string-variable = string-expression 

RT command (see RIGHT) 

RUN command 

Start executing the current program at the beginning. 

RUN 



SCREEN command 

Define a virtual screen. 

• as a graphics screen: 

SCREEN /# stream] GRAPHICS [width /FIXED/, height /FIXED/; 
/MINIMUM width,height] 

/MAXIMUM width,height] 

/UNIT width,height] 

/INFORMATION logical-expression] 

• as a text screen: 

SCREEN [#stream] TEXT [width [FIXED], height /FIXED// 
/MINIMUM width,height] 

/MAXIMUM width,height] 

/UNIT width,height] 

/INFORMATION logical-expression] 

• as a text screen with width equal to the window: 

SCREEN [#stream] TEXT FLEXIBLE 
/MINIMUM width,height] 

/MAXIMUM width, height] 

/UNIT width,height] 

/INFORMATION logical-expression] 


SELECTOR command 

Display a file selector and set the file selector values. 

SELECTOR [path-string][,file-string] 

SELFILES function 
SELPATHS function 
SELWILDS function 

Return the components of the file name and path set by the file selector. 

SELFILES 

SELPATHS 

SELWILDS 
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SET command 

Define the default text properties. 

SET /# stream] 

/WRAP logical-expression] 

/COLOUR colour] 

/EFFECTS effect-bits[,effect-bits]] 

/FONT font] 

/POINTS point-size] 

/ANGLE angle-in-degrees] 

/MODE write-mode] 

/MARGIN position] 

/ZONE zone-width] 

SGN function 

Return the sign of the given value. 

SGN ( numeric-expression ) 

SHAPE command 

Draw a polygon with (at least 3) vertices at points (x;y). 

SHAPE /# stream,] list of: x;y 

/FILL /only; /WITH fill-style]] 

/WIDTH line-width] 

/STYLE line-style] 

/COLOUR colour] 

/MODE write-mode] 

SIN function 

Return the sine of the given angle. 

SIN ( numeric-expression ) 

SQR function 

Return the square root of the given non-negative value. 

SQR ( numeric-expression ) 

STOP command 

Stop execution of the program. 

STOP 

STR$ function 

Return the string representation of the given value. 

STR$ ( numeric-expression ) 

STREAM command 

Set the default stream number. 

STREAM #stream 





STRINGS function 

Return a string of a given multiple of the given character. 

STRINGS < integer-expression, character-specifier) 

SWAP command 

Swap the contents of two variables. 

SWAP variable,variable 

SYSTEM command 

Leave BASIC and return to system level. 

SYSTEM 

TAN function 

Return tangent of given angle. 

TAN (.numeric-expression) 

TEST function 

Return the colour being displayed at point (x;y) in a graphics screen. 

TEST ([#stream,] x;y) 

TEXT command 

Screen control. 

• Clear part of a text or graphics screen. 

TEXT [#screen] CLEAR quantity 

where quantity can be EOL, BOL. LINE, EOS. BOS. SCREEN 

• Delete a line or character from a text screen. 

TEXT [#screen] DELETE /LINEj 

• Insert a line into a text screen. 

TEXT [#screen] INSERT LINE 

• Move the cursor up or down the given number of lines in a text or graphics screen. 

TEXT (#screenl FEED integer-expression 

THEN command (see IF) 

TIME function 

Return the time in hundredths of a second since midnight. 

TIME 

TOWARD function 

Returns the bearing of point (x.y) from the turtle. 

TOWARD ( [#$tream,]x; y) 

303 


1/ SYNTAX SUMMARY 





TRUE value 


TRUNC function (synonym for FIX) 

TYPE command 

Type file to the Dialogue window. 

TYPE filename 

UNIQUE function 

Return a unique value for the given file. Mainly for use as a key which will uniquely 
identify a record. 

UNIQUE #stream 
UNTIL command (see REPEAT) 

UPPER function 

Return the upper bound of the given dimension of an array. 

UPPER ( array-namei ) [,integer-expression]) 

UPPERS function 

Return the given string converted to upper case. 

UPPERS ( string-expression) 

USER ORIGIN command 

Set graphics screen origin to (x;y). 

USER [#stream,] ORIGIN x;y 

USER SPACE command 

Set graphics screen user coordinate space. 

USER [#stream,] SPACE size 

where size is width, height or dimension 

VAL function 

Return a numeric value equivalent to the given string. 

VAL ( string-expression) 

VERSION function 

Determine which version of BASIC is in use. 

VERSION (.integer-expression) 

VPOS function 

Return the position of the line on which the cursor is positioned. 

VPOS /<# stream)] 



WEND 


WHILE 


WHOLES 


WINDOW CLOSE 


WINDOW CURSOR 


WINDOW FULL 


WINDOW 

INFORMATION 

WINDOW MOUSE 


WINDOW OPEN 


WINDOW PLACE 


command (see WHILE) 

Mark the end of a WHILE loop. 

WEND 

command 

Obey the sequence of commands in the WHILE loop (terminated by WEND) whilst 
the given expression is true. 

WHILE logical-expression 
WEND 
function 

Return the whole of a fixed length string, irrespective of any nulls. 

WHOLES ( string-expression ) 

command 

Make a window invisible. 

WINDOW [#stream] CLOSE 

command 

Make the cursor in the given window visible or invisible. 

WINDOW /# stream] CURSOR logical-expression 

command 

Make a window its full size or reduce it from its full size. 

WINDOW /# stream] FULL logical-expression 

command 

Display the given text in the window’s information line. 

WINDOW /# stream] INFORMATION string-expression 

command 

Change the form of the mouse pointer in the given window. 

WINDOW /# stream] MOUSE integer-expression 

command 

Make a window visible. 

WINDOW [#stream] OPEN 

command 

Move a window to point (xpixel;ypixel). 

WINDOW /# stream] PLACE xpixel;ypixel 
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WINDOW SCROLL command 

Scroll a window over its virtual screen to set it to point (x;y). 

WINDOW [#stream] SCROLL x;y 

WINDOW SIZE command 

Make a window the given size. 

WINDOW (#stream) SIZE width,height 

WINDOW TITLE command 

Set the title displayed for the given window. 

WINDOW [#stream] TITLE string-expression 

XACTUAL function 

Return the actual width of the window in pixels. 

XACTUAL [(.#stream)] 

XBAR function 

Return the width of the right hand window border in pixels 
XBAR [(.#stream )/ 

XCELL function 

Return the width of a character cell in user coordinates. 

XCELL [(.#stream) ] 

XDEVICE function 

Return the width of the device in pixels. 

XDEVICE /(# stream)] 

XMETRES function 

Return the width of the device in metres. 

XMETRES ((^stream) ] 

XMOUSE function 

Return the x-coordinate of the position of the mouse on the real screen in pixels. 

XMOUSE 

XOR operator 
XPIXEL function 

Return the width of a pixel in user coordinates. 

XPIXEL [(#stream ) J 




XPLACE function 

Return the x-coordinate of the position of the window on the screen in pixels. 
XPLACE ((.^stream) ] 

XPOS function 

Return the x-coordinate of the cursor position in user coordinates. 

XPOS [(.#stream) ] 

XSCROLL function 

Return the x-coordinate of the position of the window on the virtual screen. 
XSCROLL [(.#stream)] 

XUSABLE function 

Return the usable width of the screen in pixels. 

XUSABLE 

XVIRTUAL function 

Return the width of a graphics screen in user coordinates. 

XVIRTUAL ((.^stream)] 

XWINDOW function 

Return the width of the window in pixels. 

XWINDOW [(.#stream)] 

YACTUAL function 

Return the actual height of the window in pixels. 

YACTUAL [(.#stream)] 

YASPECT function 

Return the aspect ratio of the user coordinates, y to x. 

YASPECT [(.#stream)] 

YBAR function 

Return the height of the bottom window border in pixels. 

YBAR [(.^stream) ] 

YCELL function 

Return the height of a character cell in user coordinates. 

YCELL /<#stream) ] 
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YDEVICE function 

Return the height of the device in pixels. 

YDEVICE [(^stream) ] 

YMETRES function 

Return the height of the device in metres. 

YMETRES [(.#stream)] 

YMOUSE function 

Return the y-coordinate of the position of the mouse on the real screen in pixels. 

YMOUSE 

YPIXEL function 

Return the height of a pixel in user coordinates. 

YPIXEL /(# stream ) ] 

YPLACE function 

Return the y-coordinate of the position of the window on the screen in pixels. 

YPLACE [(^stream) ] 

YPOS function 

Return the y-coordinate of the cursor position in user coordinates. 

YPOS [(,#stream)] 

YSCROLL function 

Return the y-coordinate of the position of the window on the virtual screen. 

YSCROLL [(# stream) ] 

YUSABLE function 

Return the usable height of the screen in pixels. 

YUSABLE 

YVIRTUAL function 

Return the height of a graphics screen in user coordinates. 

YVIRTUAL [(.#stream)] 

YWINDOW function 

Return the height of the window in pixels. 

YWINDOW [(.^stream)] 

ZONE command 

Set print zone size on Dialogue stream. 

ZONE integer-expression 
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USING PRINTERS FROM BASIC 2 
ON THE AMSTRAD PC 


Text output 

Use the PRINT command with stream #0, or use the LPRINT command. By default, 
both of these print to the DOS device LPT1. 

To use other DOS devices, you will need to first assign one of BASIC 2's streams 
to that device. This is done with the command 

OPEN Hstream PRINT device-number 

stream is the number of the stream to be used in PRINT commands 
device-numbens the number corresponding to the DOS device as follows 


0 

PRN 

1 

LPT1 

2 

LPT2 

3 

LPT3 

4 

COM1 

5 

COM2 


As with all of BASIC 2's streams, you should quote the stream number in all output 
statements which do not use the default device. You can change the default stream 
at any time with the STREAM command. 

Graphics output 

Graphics output can be printed on a matrix or laser printer either by copying the 
screen to the printer using DOS’s screen dump feature, or by using a printer as a 
graphics device within BASIC 2. Whilst using the screen dump is simpler, it only 
gives output with the same resolution as the screen. Using a printer as a graphics 
device can give far superior quality. 




NOTE: 


USING the DOS Screen Dump 

To use this feature you must run GEM from MS-DOS, not DOS Plus. To do this, load 
DOS from disc 1 (MS-DOS start-up disc), but do not load GEM yet. 

You first have to use the GRAPHICS and MODE commands to set up your PC and 
its printer. 

Use the GRAPHICS command to prepare DOS to print graphics screen displays. If 
you have an IBM PC Graphics Printer or compatible printer (such as the Amstrad 
DMP 3000) simply type 

GRAPHICS 

If you have an IBM PC Color Printer or compatible printer type 

GRAPHICS COLOR1/R 

Use the MODE command to set the printer to 8 lines per inch. Type: 

MODE LPT1 :,8 

Now load GEM and BASIC 2. To do this, insert the GEM Start-up disc, type GEM 
and follow the instructions on the screen. When the screen shows the items you 
wish to output to the printer, hold down the SHIFT key and press Prt Sc. A copy of 
your screen will then be printed. 

To use other printers and for other options of this feature, see the GRAPHICS 
command in your PC's manual. 

Using Graphics Devices in BASIC 2 

You can produce very high resolution text and grapics with matrix or laser printers, 
so graphics output can take up a lot of your PC’s memory. It is therefore essential 
that you provide BASIC 2 with as much memory as possible in order to achieve the 
best results. Even then, DOS and GEM themselves take up so much memory that 
you may not have sufficient memory to produce the results you want. 

To give BASIC 2 the maximum amount of memory take the following steps 

• Upgrade your PC to 640K of memory 

• Remove all desk accessories 

• Remove all unnecessary printer fonts. 

• Run BASIC 2 from MS-DOS, not from DOS Plus. MS-DOS is smaller. 

• Remove any RAM (or memory) disc 

Your PC supplier (or manufacturer) should help you to upgrade your PC to 640K. 
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To remove desk top accessories. Load the GEM desktopin the normal way. Insert 
your GEM start-up disc (or select your hard disc) and open the GEMBOOT folder. 
You will see a number of files displayed with a filetype .ACC. For each of these in 
turn: select the file by clicking on it once, pull down the File menu and click on Info/ 
Rename. Change the name to have a file type other than .ACC (for example just 
delete the final C). 

Check that all the accessories have been removed by restarting GEM, and pulling 
down the DESKTOP menu. No accessories should be listed. If there jure still some 
accessories listed, then check through all the folders on your start-up disc for other 
.ACC files, and treat them in a similar way. (When you want to reinstate the 
accessories, simply restore their names to have filetype .ACC) 

To remove unnecessary fonts. Use a text editor (or a word processor that can read 
and write ASCII files) to edit ASSIGN.SYS in the GEMSYS folder. If you like, you can 
use the BASIC 2 editor for this - it doesn't matter that it is not a BASIC program! 

It is a good idea to make a copy first, calling it something like ASSIGN.OLD. This 
gives you a back-up in case of disaster. 

Move down to the section which starts with a number in the printers range (21 -30) 
and a description of the printer you are going to use. For example: 

21 EPSMONH6;IBM/Epson Graphics Printer High Resolution mode 
;Prlnter Parallel Port#1 (LPT1:) 

If you can’t find a section corresponding with your printer, stop now. Youwillneed 
to add details of your printer at this point and you will need to install a compatible 
'printer driver’ for GEM to use. Consult p499 of your PC manual or ask your dealer 
if you do not know how to do this. 

If there is a section corresponding with your printer, all is well! Remember the 
number used to start the section (most likely 21, but it could be anything in the 
range 21-30). You will need to quote this as the device-number in BASIC 2’s OPEN 
command. 

Following this, there is a list of 'fonts'. These take the form 

EPSHSS10.FNT; £PSON HI Res (120x144 dots/inch) Swiss 10 point 

Remove as many of these as you can. Ideally, choose to use a single style of text, 
such as SWISS and a single small point size such as 7 or 10. You will then have that 
size and style of text available on your printer, plus the same font at twice the size. 

Now save the file back as your new (smaller) ASSIGN.SYS and you are ready to run 
BASIC 2 using the printer for text and graphics. 



To run GEM from DOS with no RAM disc 


On a hard disc PC: If you have set your PC up to load MS-DOS or to offer you a choice 
of operating system, then you just need to start your PC as normal and, if necessary, 
select MS-DOS. If you are not sure, or you always use DOS Plus, then you should 
start your PC with the red MS-DOS disc 1 and type C: to select the hard disc. In both 
cases, start GEM by typing the command GEMSTART. 

On a floppy disc PC: The simplest way of running under DOS with no RAM disc 
is to create a new start-up disc specially for this purpose. Have a new blank disc 
and copies of your Amstrad master discs to hand and follow these instructions: 

Format the blank disc for use as a system disc. To do this, insert the red MS-DOS 
Disc 1 into drive A. If you are not using MS-DOS, reset your PC and load MS-DOS 
from this disc. Then type: 

FORMAT A'JS 

and replace the MS-DOS disc by the blank disc when prompted. 

Use the COPY command to copy the following files from Amstrad Disc 1 onto the 
new disc. 

CONFIG.SYS 
AUTOEXEC.BAT 
KEYBUK.EXE 
MOUSE.COM 
To do this: 

1 Insert the red MS-DOS Master disc in Drive A 

2 On a two-drive PC, insert the new disc in Drive B 

3 Type COPY A:CONFIG.SYS B: 

4 (On a single-drive or hard-disc PC, swap discs when prompted) 

5 Repeat for the other files 

Use the COPY command as above to copy the file GEMSTART.BAT from the blue 
GEM Start-up disc 2 to the new disc. 

Use the XCOPY command with the /S option to copy the directories GEMBOOT and 
GEMSYS and their subdirectories from Amstrad GEM Start-up Disc 2 (Blue) to the 
new disc. To do this: 



First, create new directories on the new disc 

1 Insert the new disc in Drive A 

2 Type MKD1R GEMBOOT 

3 Type MKDIR GEMSYS 

Then, copy the contents of the directories 

1 Insert the red MS-DOS Start-up disc 1 into Drive A 

2 Type XCOPY AiGEMBOOT B:GEMBOOT /S/W 

3 Insert the blue GEM Start-up disc 2 into Drive A 

4 On a two-drive PC insert the new disc in Drive B 

5 Press a key as directed, to start the XCOPY 

6 (On a single-drive or hard disc PC swap discs when prompted) 

7 Repeat for GEMSYS 

Use a text editor (such as RPED) or a word processor that can handle ASCII files to 
edit CONFIG.SYS on the new disc. Remove the line starting DEVICE = 
RAMDRIVE.SYS. 

To use GEM with the new disc, insert the disc in drive A and reset your PC. At the 
DOS A> prompt, type GEMSTART and press Return. 

As you no longer have the RAM disc available, you may encounter problems when 
you want to leave GEM and return to DOS. To solve these, you should add 
COMMAND.COM to the GEM Desktop disc and ensure that this disc is in drive A 
whenever you select Exit to DOS. To add this to the GEM Desktop disc, copy the 
file COMMAND.COM from the MS-DOS disc using the COPY command as above. 
You will first need to make room for COMMAND.COM on the Desktop disc by 
erasing DOODLE.APP and DOODLE.RSC. 

To test and to use BASIC 2 to print graphics 

Follow the above instructions to load GEM from DOS. Load BASIC 2, and before 
going any further, check that your graphics printer works. This can be done by a 
simple BASIC 2 program: 

OPEN #5 DEVICE 21 
CIRCLE #5, 2500;2500,2000 
PRINT #5, “Hello There" 

GRAPHICS #5 UPDATE NEW 


This assumes that the device-number of your graphics printer is 21. If it isn’t, 
substitute the number you remembered above. 

If this program runs it should produce the text Hello There and a circle on your 
graphics printer. If it produces the error Gem error in the Dialogue window, you 
need to free off more memory. It is likely that you have some other software which 
is in memory or have not been brutal enough in following all the above steps. Check 
too that the printer font you kept in ASSIGN.SYS has a small point size (say 10 or 
7) - the larger the point size, the more memory a high resolution printer font takes. 

Once you have succeeded in making this short test work, you can go on to write 
BASIC 2 programs which use the printer effectively. All you can display on a 
graphics virtual screen you can print on the graphics printer. However, you do 
need to start with the OPEN DEVICE command and must use the stream number 
(or change the default stream) in all you graphics output commands. 

Also, nothing will be printed until you issue the GRAPHICS UPDATE command, at 
which point the whole page will be printed. Unlike a screen (or a plotter), you cant 
show each command as it happens - printers just don't work that way. 

The final thing to check is that you are working with the coordinates you expect. 
A screen is normally wider than it is high and so by default is about 5000 units high 
and 8000 wide. The printer on the other hand is longer than it is wide and so is only 
5000 units wide. You may therefore need to use the USER SPACE command to set 
printer coordinates to match those on the screen. For the default screen dimen¬ 
sions and an IBM PC Graphics Printer, you can do this by the command: 

USER tiprinter-stream SPACE XVIRTUAL (^screen-stream) 

If you have a different printer or have changed the aspect ratio of the screen, you 
will need to experiment with other values to get the desired result. 



FURTHER INFORMATION AND ERRATA 

• Running a BASIC 2 program direct from a DOS prompt 

Ensure that there are valid active PATHS to the files GEMVDI.EXE and 
BASIC2.APP. (Refer to your DOS and GEM documentation for information on how 
to do this.) Then issue the following DOS command: 

GEMVDI BASIC2 program 

where program is the full path-name of your BASIC2 program. 

• Using DOS devices 

DOS devices (such as COM1) can be accessed in just the way you might expect by 
using the device name as a filename. For example, 

OPEN #5 INPUT “COM1" 

will open the serial input device COM1 as stream 5. Then INPUT or LINE INPUT 
commands can be used to fetch characters from COM1. Similar commands can be 
used for output and for other DOS devices. 

You cannot access machine code directly from BASIC 2 (this is planned for a future 
release) but many device access problems can be solved by creating a DOS device 
driver. For details see the Microsoft publication ‘MS-DOS Programmers Reference’. 

• Item Selectors 

This edition of the BASIC2 Users Guide describes the SELECTOR command (and 
associated commands) for the manipulation of Item Selectors (page 262a). These 
commands are only incorporated in versions 1.14 and above. If your version is 1.12 
or 1.13, you can update to the latest version: full details are given in the Locomotive 
Systems price list. 

• Reposition command (Keyed file handling) 

The Reposition command moves the current position in the Index file to another 
index entry that points to the same record in the Data file. This makes it 
straightforward to retain the data record you are working on while stepping from 
index to index within the Index file. 

The syntax of the command is: 

REPOSITION Hstream KEY key /INDEX index]] LOCK lock] 

where key and index identify the position in the Index to which the move is to be 
made. (If index isn’t specified, then the key is assumed to be in the current index.) 
The command will fail if there isn’t an entry in the index with this key value that 
points to the same record in the Data file. 





• Errata 


page 145: Note: The shorter edge of a screen is set to 5000 user coordinates 
long unless this makes the longer edge more than 32767 user coordinates 
long. In that case, the longer edge is set to 32767 user coordinates and the 
shorter edge is set in proportion. The shorter edge is then less than 5000 
user coordinates long. 

page 146: The description of the PLOT command is incorrect. The value 
required by MARKER SIZE must be in the range 1...255 and gives the size 
of the marker in pixels. Note that there may not be a smooth gradation of 
sizes. Also, delete the reference to Appendix HI in the description of marker- 
type s. 

page 156: Note: The TEST function may not be available on your system as it 
depends on the version of the underlying software you are using. 

page 169: Note: When a graphics virtual screen is set up, the shorter edge of a 
screen is set to 5000 user coordinates long unless this makes the longer 
edge more than 32767 user coordinates long. In that case, the longer edge 
is set to 32767 user coordinates and the shorter edge is set in proportion. The 
shorter edge is then less than 5000 user coordinates long. 

Similarly, if the dimension specified in a USER [t stream, /SPACE dimension 
command would make the longer edge more than 32767 user coordinates 
long, the longer edge is automatically set to 32767 units and the shorter 
edge is again set in proportion. 

page 172: The device number to quote when using the OPEN PRINT command 

depends on the DOS device you wish to use (see your computer's operating 
system manual). The number to use should be taken from the following 
table: 


Device Device number 


PRN 0 

LPT1 1 

LPT2 2 

LPT3 3 

COM1 4 

COM2 5 


Different device numbers are used in an OPEN DEVICE command. The 
ranges in which the numbers you will require lie are given in the table on 
page 172, but the actual number you need is the one associated with your 
chosen device in the ASSIGN.SYS file (see your computer's operating system 
manual). 



page 211: The FIXED parameter of the DIM stored$ statement in the program 

should be 9, not 17. 

page 221-223: The example program 'Creating a simple random file' should be: 
flleno=5 

filename$="lines" 

reclength=40 

RECORD n; person$ FIXED reclength 
ld$=STRiNG$(reclength,0) 

OPEN #flleno RANDOM filenames LENGTH reclength 
REPEAT 

INPUT "Type name then RETURN, or RETURN to quit", id$.n.person$ 

IF id$.n.person$<>"" THEN PUT #flleno,ld$:POSITION #flleno, NEXT 
UNTIL id$.n.person$="" 

CLOSE 

Note the step ld$=STRING$(reclength,0) which initialises the string which 
will hold the record (see page 96) and the testing in the REPEAT loop of the 
value of the string element ld$.n.person$, rather thanof the whole stringidS 

page 225: The 5th line of the program should read: 

OPEN #fileno RANDOM filenames LENGTH reclength 

page 244: The ADDREC command should read: 

ADDREC #flle, r$ KEY UPPER$(sex$) INDEX sexjndex 

This ensures that the key is recorded as a capital letter. 

page 288: The syntax of the EXTENT command given on page 288 is incorrect. 

It should read: 

EXTENT ([ttstream,] [print-functions,] print-string) 

page 299: The syntax of the REPOSITION command given on page 299 is 
incorrect. It should read: 

REPOSITION #stream KEY key /INDEX index] /LOCK lock] 

Index: The INSTR command has been omitted from the index. This 

command is described on page 119. 
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Reference by key, 231 
Renaming files, 190 
Sequential files. 192 
Structured files, 213 
Summary, 246 
Writing, 218 
FILL 

In GRAPHICS command, 156 
In graphics commands, 149 
FILL ONLY, 149 
Filling areas of the screen, 155 
FINDS, 190 
FINDDIRS, 191 
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Integers, 41, 89 
Interrupting programs, 88 
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For keyed files, 233 
For random files. 215 
In OPEN command, 193 
NEXT 

For file position, 218 
In FOR command, 185 
In POSITION, 237 
In RESUME command, 251 
NOT. 110, 183 
Null string, 91 
Numbers. 19, 41, 89 
Binary precision, 98 
Converting to binary string, 120 
Converting to formatted decimal 
string, 120 

Converting to hexadeximal string, 120 
Converting to text strings, 120 
Formatting numbers, 128 
Magnitude, 113 
Range of numbers, 41, 90 
Rounding, 114 



Scientific format. 89 
Signs, 113 
Numeric data. 41 
Numeric expressions 
As TRUE and FALSE. 183 
Comparing numeric expressions, 183 
Numeric functions, 111 
Numeric variables, 98 

OLD 

For keyed files. 233 
For random files, 215 
In OPEN command, 193 
ON ERROR GOTO, 250 
ON GOTO/GOSUB, 181, 184 
OPEN, 161, 163 
In WINDOW command, 164 
Keyed files. 233 
Opening disc files, 192 
OPEN APPEND, 193 
OPEN DEVICE, 172 - 
OPEN INPUT, 193 
OPEN OUTPUT, 193 
OPEN PRINT, 144, 161, 172 
OPEN RANDOM. 215 
OPEN WINDOW, 163 
Opening a printer stream, 144 
Opening files, 192 
Opening windows, 164 
Operating system errors, 249 
Operators, 21, 56, 107 
Arithmetic, 108 
Binary, 110 
Logical, 110 

Precedence. 109, 111, 117 
Relational, 111 
String, 117 

OPTION CURRENCYS, 255 
OPTION DATE, 256 
OPTION DECIMAL, 255 
OPTION DEGREES, 255 
OPTION RADIANS, 255 
OPTION RUN. 256 
OPTION STOP, 256 
OPTION TRAP, 257 
OR. 110, 183 
OSERR, 249 
Output, 63, 123 
Formatting output, 65 
Graphics output, 144 
In Windows. 132 
To a printer. 143 
To a stream, 162 


OUTPUT 

In OPEN command, 193 

Parameters, 18, 85 
Function parameters. 180 
Paths. 189 
Patterns menu, 277 
Phone book program (example), 200 
PIE, 152 
Pie segments 

Drawing circular pie segments. 152 
Drawing elliptical pie segments. 153 
PIQ program (example), 205 
Pixels, 69.159 
Reading colour. 156 
PLACE 

In WINDOW command. 166 
PLOT. 146 
Plotting points, 146 
POINT, 157 
POINTS 

In SET command. 138 
Print function, 138 
POINTSIZE, 138 
Polygons 

Drawing polygons. 153 
POS. 126, 137 
POSITION. 237 
Position 
In files. 218 
In keyed file, 237 
POSITIONS. 218 
Positioning text. 125 
Positioning the cursor. 126, 136 
Pound sign. 255 
Printing. 129 
Powers. 112 
PRINT. 44. 64. 125 
In OPEN command. 144. 161. 172 
To a disc file. 194 
Print format. 127 
Print functions. 126 
PRINT USING. 66. 127 
Print zones. 125 
Printer output. 143 
Closing a printer stream. 144 
Opening a printer stream. 144 
Printers 

As graphics devices. 172 
Printing 

Currency symbols. 129 
Integers, 128 
Real numbers. 128 



Thousands, 128 
To a disc file, 194 
Printing programs, 32, 87 
Program icon, 6 
Program layout, 177 
Program lines 
Labels, 74, 175 
Length of lines, 30 
Line numbers, 74, 175 
Order of execution, 29, 73.175 
Renumbering, 274 
Typing program lines, 30 
Program menu, 273 
Continue option, 88 
List option, 32 
New option. 28 
Run option, 88 
Save option, 87 
Stop option, 88 
Program structure, 29, 85, 175 
Programs 

Altering programs, 31. 86 
Branching programs, 80 
Continuing execution, 176 
Designing programs, 35 
Graphics example, 205 
Interrupting programs. 88 
Keyed files example, 241 
Line numbers, 85 
Phone book example, 200 
Printing programs, 32, 87 
Program layout, 177 
Program structure, 29, 85, 175 
Random hies examples. 221 
Renumbering. 274 
Restarting programs, 249 
Running programs, 11, 88 
Saving on disc, 87 
Statements, 85 
Statistics example, 198 
Stop and continue, 88 
Stopping a program, 88, 176 
Testing, 248 
Typing programs. 30 
Writing programs, 27 
Pseudoconstants, 43 
PUT, 218 

To change a keyed file, 240 
Quote marks, 19, 90 
RAD, 112 

Radians, 57, 112, 255 


RADIANS 

In OPTION command, 255 
RANDOM 

In OPEN command. 215, 233 
Random files, 213 
Closing. 220 
Creating, 215 
Example programs, 221 
Locking, 260 
Opening. 215 
Structure of data. 215 
Random numbers, 113 
RANDOMIZE, 113 
RD, 191 
READ, 44, 101 
Reading files, 195 
End of file, 197 
Reading keyed records, 238 
Reading records from a file, 219 
Real numbers, 89 
RECORD 

For random files, 216 
Record fields, 213 
Record length 
For keyed files, 233 
Record locking, 261 
Record numbers, 214 
Records, 95. 213 
Assigning to record fields, 96 
Changing in a file. 220 
Current position, 218 
Fields. 95 

For keyed files, 235 
In a random file. 215 
Initialising records, 96 
Locking records, 261 
Reading from a file, 219 
Selecting, 214 
Writing to a file. 218 
Rectangles 

Drawing rectangles, 154 
With rounded corners, 154 
Relational operators, 111, 182 

REM. 177 

REN, 190 

Renaming files, 190 
Renumbering programs. 274 
REPEAT, 187 

Repeating instructions, 75, 185 
Replace mode, 140, 146 
RESET 

In CLS command, 131 




Restarting programs, 249 
After errors, 251 
RESTORE, 101 
Results-1 window, 9, 68 
Initial size, 134 
Results-2 window, 9, 68 
RESUME. 251 
RETURN, 178 
Return codes, 250 

Reverse transparent mode, 140, 146 

Reversed-out text, 131 

RIGHT, 157 

RIGHTS, 118 

RMDIR. 191 

RND. 113 

ROUND, 114 

ROUNDED (In BOX command), 154 

Rounding, 98. 114 

Rows. 124, 134 

RSET, 99 

RT, 157 

RUN 

In OPTION command, 256 
Running programs. 11, 88 

Saving programs, 87 
Scaled numbers, 89 
The screen, 269 
Dimensions, 269 
SCREEN. 167 
Screen control, 67 
Screen dimensions, 134 
SCREEN GRAPHICS, 168 
SCREEN TEXT, 167 
Screens 

Clearing the screen. 125 
Columns, 134 
Dimensions, 134 
Lines, 134 
Positions on, 134 
Size of. 160 
Usable area, 160 
User coordinates, 134 
Virtual screens, 8 
SCROLL 

In WINDOW command, 165 
Scroll bars 
Size of, 166 

Scrolling windows. 8, 135,164 
Selecting records, 214 
Separators 

Between statements, 85 
Thousands separator, 255 


Sequential files 
Changing a file, 197 
Locking. 260 

Using sequential files. 197 
SET. 131 
SET WRAP. 132 
SET ZONE. 125 
SGN. 113 
SHAPE. 153 
Signs (of numbers). 113 
SIN. 112 
SIZE 

In GRAPHICS command. 156 
In PLOT command. 146 
In WINDOW command. 165 
Sizing windows. 8 
Spaces 

After commands. 18 
As format characters. 128 
SQR, 112 
Square roots. 112 
Squares 

Drawing squares, 154 
With rounded comers. 154 
START 

In GRAPHICS command. 156 
In graphics commands. 147 
In Turtle graphics. 157 
Starting BASIC 2. 5 
Failure. 7 
Statements. 85 
Statistical functions. 113 
Statistics program (example). 198 
STEP 

In FOR command. 185 
STOP. 176 

In OPTION command. 256 
Stop and continue. 176 
Stopping programs, 88. 176 
Storage classes 
In an array. 94 
STR$. 120 
STREAM. 162 
Stream 0.143 
Stream numbers. 133 
Streams. 133 
As disc files. 195 

Assigning a window to a stream. 162 
Changing the default stream. 162 
Closing a stream. 163 
Default stream. 133 
Defining streams, 161 
Opening for use. 161 



Specifying a stream, 63 
Stream numbers, 133 
String expressions 
Comparing string expressions. 183 
String functions, 117 
String operators. 117 
String variables, 92 
Assigning to string variables. 99 
Assigning to substrings, 99 
Fixed length, 92. 95 
Variable length, 92 
STRINGS. 96. 118 
Strings, 19, 90 

Converting to lower case, 119 
Converting to numbers, 115 
Converting to upper case, 119 
Determining length, 119 
Manipulating strings. 58 
Null string, 91 
String constants, 90 
String functions. 117 
String operators. 117 
String variables, 92 
Substrings, 58, 117 
Text strings. 42 
Structured files, 213, 213 
Structured variables, 95 
STYLE 

In GRAPHICS command, 156 
In graphics commands. 147 
In Turtle graphics, 157 
Subroutines. 178 
Substrings, 58. 100, 117 
SWAP. 97 
Syntax, 17 
Summary. 281 
Syntax errors, 18 

TAB (Print function), 126 
TAB characters 
Interpretation by a printer, 143 
TAN, 112 
Template 

For decimal string, 120 
For text output, 127 
TEST. 156 

Testing programs, 248 
TEXT CLEAR, 142 
TEXT DELETE. 142 
Text fonts, 137 
TEXT INSERT. 143 
Text output. 63, 64, 123 
Angled, 140 


Colour, 130 
Control codes, 125 
Escape sequences, 127 
Formatted output, 127 
Indentation, 141 
Margins, 141 

Mixing with graphics, 140 
On graphics screens, 135 
Positioning text, 125 
Positioning the cursor. 126 
Print zones, 125 
Text style, 130 
To a stream. 162 
Write mode. 140 
Text screens, 133 
Clearing parts of the screen, 142 
Coordinates, 134 
Defining a text screen, 167 
Erasing displayed text, 142 
Inserting lines, 143 
Text size, 137 
Setting default size, 138 
Text strings, 19. 42, 117 
Converting case of, 119 
Converting to numbers, 115 
Determining length, 119 
Formatting text strings, 128 
Generating, 118 
Of the same character, 118 
Predicting length, 136 
Text style, 130 
Default text style, 141, 271 
Escape sequences, 131, 141 
Resetting text style, 131 
Setting default style. 137 
Text fonts. 137 
Text size, 137 
Text windows, 67 
THEN 

In IF statements. 181 
Thick text, 131 
Thousands 
Printing, 128 
Separator, 255 
TIME, 105 
TITLE 

In WINDOW command, 167 
TO keyword, 93. 100, 117 
In FOR command, 185 
Top window, 166 
TOWARD. 157 
Transparent mode, 140, 146 



TRAP 

In OPTION command, 257 
Trapping errors, 250 
Trapping undefined variables, 257 
Trigonometric functions, 112 
TRUE, 110 
Boolean value, 110 
TRUNC, 114 

Truncating numbers, 114 
Truth table, 111 
Turtle graphics, 156 
Cursor, 156 
Drawing lines, 157 
Moving the turtle. 157 
Turning the turtle, 157 
TYPE. 190 

Typing programs, 30 

UBYTE (storage class). 94 
Unary operators, 108 
Undefined variables. 257 
UNIQUE, 235 
In KEYSPEC, 234 
UNIT 

In SCREEN command, 167 
Unsealed numbers, 41, 89 
UNTIL, 187 
UPDATE 

In GRAPHICS command, 172 
Upper case 

Converting strings to upper case, 119 
UPPERS, 119 

User coordinates. 69. 134, 145, 270 
Defining size, 169 
USER ORIGIN, 170 
USER SPACE, 169 
USING 

In DECS function, 120 
In PRINT command, 66. 127 
UWORD (storage class), 94 

VAL. 115 

Variable names, 91 
Choosing variable names, 20. 48 
How displayed, 20 
Variables, 20, 47. 91 
Assigning values, 97 
Lifetime, 49 

Numeric variables, 49. 98 
String variables, 49. 92, 99 
Structured variables, 95 
Swapping values, 97 
Undefined variables. 257 


Virtual screens. 8, 67,132 
Aspect ratio. 169 
Changing origin. 170 
Closing a virtual screen, 163 
Defining a graphics screen, 168 
Defining a text screen. 167 
Dimensions. 167, 270 
Graphics outside screen area, 151 
Initial definitions, 162 
Opening for use. 161 
Size of. 170 
VPOS, 126, 137 
VT52 emulation. 67 

WEND. 187 
WHILE, 187 
WHOLES. 99 
WIDTH 

In GRAPHICS command. 156 
In graphics commands, 147 
In Turtle graphics, 157 
WINDOW 

In PRINT command. 161 
WINDOW CLOSE. 164 
WINDOW CURSOR. 132. 165 
Window dimensions, 134 
WINDOW FULL. 166 
WINDOW INFORMATION. 167 
WINDOW MOUSE. 171 
WINDOW OPEN. 164. 166 
WINDOW PLACE. 166 
WINDOW SCROLL. 165 
WINDOW SIZE. 165 
WINDOW TITLE. 167 
Windows. 8, 67, 164 
Assigning a window to a stream. 162 
Automatic scrolling, 165 
Bringing to the top. 166 
Closing windows. 164 
Columns. 124 
Determining size, 166 
Dialogue window. 9. 68 
Dimensions. 269 
Edit window. 9. 68 
Graphics windows. 67 
Information line, 167 
Initial definitions. 162 
Lines. 124 
Moving windows. 8 
Opening windows, 164 
Output to a window. 124 
Position on display. 166 
Position on virtual screen. 165 



Results-1 window, 9, 68 
Results-2 window, 9, 68 
Scroll bars, 166 
Scrolling, 8,135, 164 
Setting size, 8, 165 
Text windows, 67 
Title. 167 
Visibility. 164 
Windows menu, 278 
WORD (storage class), 94 
Wrapping, 132 
Write modes, 140 
In graphics commands. 146 
Writing keyed files, 235 
Writing programs, 27 
Writing records to a file, 218 

XACTUAL, 166 
XBAR, 166 
XCELL, 136 
XDEVICE, 160 
XMETRES, 170 
XMOUSE. 104 
XOR, 110, 183 
XOR mode, 140, 146 
XPDCEL, 169 
XPLACE, 166 
XPOS, 137 
XSCROLL, 165 
XUSABLE, 160 
XVIRTUAL, 145 
XWINDOW, 166 

YACTUAL, 166 
YASPECT, 170 
YBAR, 166 
YCELL, 136 
YDEVICE, 160 
YMETRES, 170 
YMOUSE, 104 
YPIXEL, 169 
YPLACE, 166 
YPOS, 137 
YSCROLL, 165 
YUSABLE, 160 
YVIRTUAL, 145 
YWINDOW, 166 

ZONE, 125 


C and D characters, 93 
\ character. 

In file names. 189 
As format character. 128 
“operator, 108 

< and > characters, 58, 117 
, character. 

As format character, 128 
In PRINT commands, 125 
" character, 19, 90 
! format character, 128 

# character, 63.133 

As format character, 128 
$ character, 92 
As format character, 129 
& character, 90 
As format character, 128 
&X, 90 

' character, 177 
( and ) characters, 93 

* / and \ operators, 108 

+ ~ 

As format characters, 128 
As operators, 108 
: character. 85 

; character in PRINT commands, 125 

< > operators, 111, 182 

<= =< >= => operators, 111, 182 
<> operator. Ill, 182 
= character, 91. 97 
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